Cart Provider Overview

useCart

This hook exposes the context of CartProvider.

The context provides helper functions and mutations for managing the cart and checkout. You can refer to the following guides for examples on how to use them:

• How to Add Cart Functionality
• How to Implement Checkout Flow

Example

src/Cart.ts

import * as React from "react"

import { useCart } from "medusa-react"

const Cart = () => {
  const handleClick = () => {
    createCart.mutate({}) // create an empty cart
  }

  const { cart, createCart } = useCart()

  return (
    <div>
      {createCart.isLoading && <div>Loading...</div>}
      {!cart?.id && (
        <button onClick={handleClick}>
          Create cart
        </button>
      )}
      {cart?.id && (
        <div>Cart ID: {cart.id}</div>
      )}
    </div>
  )
}

export default Cart

In the example above, you retrieve the createCart mutation and cart state object using the useCart hook. If the cart is not set, a button is shown. When the button is clicked, the createCart mutation is executed, which interacts with the backend and creates a new cart.

After the cart is created, the cart state variable is set and its ID is shown instead of the button.

Note

The example above does not store in the browser the ID of the cart created, so the cart’s data will be gone on refresh. You would have to do that using the browser’s Local Storage.

Returns

setCart(cart: Omit<Cart, "refundable_amount" | "refunded_total">) => voidRequired

A state function used to set the cart object.

payUseMutationResult<Response<StoreCartsRes>, Error, StorePostCartsCartPaymentSessionReq, unknown>Required

A mutation used to select a payment processor during checkout. Using it is equivalent to using the useSetPaymentSession mutation.

createCartUseMutationResult<Response<StoreCartsRes>, Error, undefined | StorePostCartReq, unknown>Required

A mutation used to create a cart. Using it is equivalent to using the useCreateCart mutation.

startCheckoutUseMutationResult<Response<StoreCartsRes>, Error, void, unknown>Required

A mutation used to initialize payment sessions during checkout. Using it is equivalent to using the useCreatePaymentSession mutation.

completeCheckoutUseMutationResult<Response<StoreCompleteCartRes>, Error, void, unknown>Required

A mutation used to complete the cart and place the order. Using it is equivalent to using the useCompleteCart mutation.

updateCartUseMutationResult<Response<StoreCartsRes>, Error, StorePostCartsCartReq, unknown>Required

A mutation used to update a cart’s details such as region, customer email, shipping address, and more. Using it is equivalent to using the useUpdateCart mutation.

addShippingMethodUseMutationResult<Response<StoreCartsRes>, Error, StorePostCartsCartShippingMethodReq, unknown>Required

A mutation used to add a shipping method to the cart during checkout. Using it is equivalent to using the useAddShippingMethodToCart mutation.

totalItemsnumberRequired

The number of items in the cart.

cartOmit<Cart, "refundable_amount" | "refunded_total">

The currently-used cart.

---

CartProvider

CartProvider makes use of some of the hooks already exposed by medusa-react to perform cart operations on the Medusa backend. You can use it to create a cart, start the checkout flow, authorize payment sessions, and so on.

It also manages one single global piece of state which represents a cart, exactly like the one created on your Medusa backend.

To use CartProvider, you first have to insert it somewhere in your component tree below the MedusaProvider. Then, in any of the child components, you can use the useCart hook exposed by medusa-react to get access to cart operations and data.

Example

src/App.ts

import { CartProvider, MedusaProvider } from "medusa-react"
import Storefront from "./Storefront"
import { QueryClient } from "@tanstack/react-query"
import React from "react"

const queryClient = new QueryClient()

function App() {
  return (
    <MedusaProvider
      queryClientProviderProps={{ client: queryClient }}
      baseUrl="http://localhost:9000"
    >
      <CartProvider>
        <Storefront />
      </CartProvider>
    </MedusaProvider>
  )
}

export default App

Parameters

param0CartPropsRequired

Props of the provider.

Returns

ElementElementRequired

CartProvider makes use of some of the hooks already exposed by medusa-react to perform cart operations on the Medusa backend. You can use it to create a cart, start the checkout flow, authorize payment sessions, and so on. It also manages one single global piece of state which represents a cart, exactly like the one created on your Medusa backend. To use CartProvider, you first have to insert it somewhere in your component tree below the MedusaProvider. Then, in any of the child components, you can use the useCart hook exposed by medusa-react to get access to cart operations and data.