Medusa React

Medusa React is a React library that provides a set of utilities and hooks for interacting seamlessly with the Medusa backend. It can be used to build custom React-based storefronts or admin dashboards.

Alternatively, you can use Medusa’s JS Client or the REST APIs.

Installation

In the directory holding your React-based storefront or admin dashboard, run the following command to install Medusa React:

• npm
• Yarn
• pnpm

npm install medusa-react @tanstack/react-query @medusajs/medusa

Report Incorrect CodeCopy to Clipboard

yarn add medusa-react @tanstack/react-query @medusajs/medusa

Report Incorrect CodeCopy to Clipboard

pnpm add medusa-react @tanstack/react-query @medusajs/medusa

Report Incorrect CodeCopy to Clipboard

In addition to the medusa-reactCopy to Clipboard library, you need the following libraries:

1. @tanstack/react-queryCopy to Clipboard: medusa-reactCopy to Clipboard is built on top of Tanstack Query. You’ll learn later in this reference how you can use Mutations and Queries with Medusa React.

Versions of Medusa React prior to v4.0.2 used React Query v3 instead of Tanstack Query. Check out [this upgrade guide] to learn how you can update your storefront.

2. @medusajs/medusaCopy to Clipboard: The core Medusa package. This is used to import types used by Medusa React and while developing with it.

Part of the Medusa roadmap is to move the types into a separate package, removing the need to install the core Medusa package in your storefront or admin dashboard. You can check other items on our roadmap in GitHub Discussions.

---

Usage

To use the hooks exposed by Medusa React, you need to include the MedusaProviderCopy to Clipboard somewhere up in your component tree.

The MedusaProviderCopy to Clipboard requires two props:

1. baseUrlCopy to Clipboard: The URL to your Medusa backend
2. queryClientProviderPropsCopy to Clipboard: An object used to set the Tanstack Query client. The object requires a clientCopy to Clipboard property, which should be an instance of QueryClient.

For example:

src/App.ts

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

const queryClient = new QueryClient()

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

export default App

Report Incorrect CodeCopy to Clipboard

In the example above, you wrap the StorefrontCopy to Clipboard component with the MedusaProviderCopy to Clipboard. StorefrontCopy to Clipboard is assumed to be the top-level component of your storefront, but you can place MedusaProviderCopy to Clipboard at any point in your tree. Only children of MedusaProviderCopy to Clipboard can benefit from its hooks.

The StorefrontCopy to Clipboard component and its child components can now use hooks exposed by Medusa React.

Troubleshooting: Could not find a declaration file for module 'medusa-react'

If you import medusa-reactCopy to Clipboard in your code and see the following TypeScript error:

Could not find a declaration file for module 'medusa-react'

Report Incorrect CodeCopy to Clipboard

Make sure to set moduleResolutionCopy to Clipboard in your tsconfig.jsonCopy to Clipboard to nodenextCopy to Clipboard or nodeCopy to Clipboard:

tsconfig.json

{
  "compilerOptions": {
    "moduleResolution": "nodenext",
    // ...
  },
  // ...
}

Report Incorrect CodeCopy to Clipboard

MedusaProvider Optional Props

You can also pass the following props to Medusa Provider:

Props	Default	Description
apiKeyCopy to Clipboard	''Copy to Clipboard	Optional API key used for authenticating admin requests. Follow this guide to learn how to create an API key for an admin user.
publishableApiKeyCopy to Clipboard	''Copy to Clipboard	Optional publishable API key used for storefront requests. You can create a publishable API key either using the admin APIs or the Medusa admin.

Queries

To fetch data from the Medusa backend (in other words, perform GETCopy to Clipboard requests), you can use Queries. Query hooks simply wrap around Tanstack Query's useQueryCopy to Clipboard hook to fetch data from your Medusa backend.

For example, to fetch products from your Medusa backend:

src/Products.ts

import { Product } from "@medusajs/medusa"
import { useProducts } from "medusa-react"

const Products = () => {
  const { products, isLoading } = useProducts()

  return isLoading ? (
    <div>
      Loading...
    </div>
  ) : (
    <ul>
      {products?.map((product: Product) => (
        <li key={product.id}>
          {product.title}
        </li>
      ))}
    </ul>
  )
}

export default Products

Report Incorrect CodeCopy to Clipboard

In the example above, you import the useProductsCopy to Clipboard hook from medusa-reactCopy to Clipboard. This hook, and every other query hook exposed by medusa-reactCopy to Clipboard, returns everything that useQueryCopy to Clipboard returns in Tanstack Query, except for the dataCopy to Clipboard field.

Instead of the dataCopy to Clipboard field, the response data is flattened and is part of the hooks’ returned fields. In the example above, the List Products endpoint returns a productsCopy to Clipboard array. So, useProductsCopy to Clipboard returns a productsCopy to Clipboard array along with other fields returned by useQueryCopy to Clipboard.

If the request accepts any parameters, they can be passed as parameters to the mutateCopy to Clipboard request. For example:

src/Products.ts

const { products } = useProducts({
    expand: "variants",
  })

Report Incorrect CodeCopy to Clipboard

You can learn more about using queries in Tanstack Query’s documentation.

Mutations

To create, update, or delete data on the Medusa backend (in other words, perform POSTCopy to Clipboard, PUTCopy to Clipboard, and DELETECopy to Clipboard requests), you can use Mutations. Mutation hooks wrap around Tanstack Query's useMutationCopy to Clipboard to mutate data on your Medusa backend.

For example, to create a cart:

src/Cart.ts

import { useCreateCart } from "medusa-react"

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

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

export default Cart

Report Incorrect CodeCopy to Clipboard

In the example above, you import the useCreateCartCopy to Clipboard hook from medusa-reactCopy to Clipboard. This hook, and every other mutation hook exposed by medusa-reactCopy to Clipboard, returns everything that useMutation returns. You can also pass the same options you would pass to useMutationCopy to Clipboard to mutation hooks exposed by medusa-reactCopy to Clipboard.

To create a cart, you call the createCart.mutateCopy to Clipboard method. In the underlying logic, this method sends a POSTCopy to Clipboard request to the Medusa backend to create a cart.

If the request accepts any parameters, they can be passed as parameters to the mutateCopy to Clipboard request. For example:

createCart.mutate({
  region_id,
})

Report Incorrect CodeCopy to Clipboard

Once the cart is created, you can access it in the dataCopy to Clipboard field returned by the mutation hook. This field includes all data returned in the response.

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

Instead of using mutateCopy to Clipboard, you can use mutateAsyncCopy to Clipboard to receive a Promise that resolves on success or throws on error.

Learn more about how you can use mutations in Tanstack Query’s documentation.

Custom Hooks

This feature is available in the betaCopy to Clipboard version of Medusa React, which also requires the betaCopy to Clipboard version of the Medusa core. You can install them with the following command:

npm install medusa-react@beta @medusajs/medusa@beta

Report Incorrect CodeCopy to Clipboard

Medusa React provides three utility hooks that allows developers to consume their admin custom endpoints using the same Medusa React methods and conventions.

useAdminCustomQuery

The useAdminCustomQueryCopy to Clipboard utility hook can be used to send a GETCopy to Clipboard request to a custom endpoint in your Medusa backend and retrieve data. It's a generic function, so you can pass a type for the request and the response if you're using TypeScript in your development. The first type parameter is the type of the request body, and the second type parameter is the type of the expected response body:

useAdminCustomQuery<RequestType, ResponseType>

Report Incorrect CodeCopy to Clipboard

The hook accepts the following parameters:

1. pathCopy to Clipboard: (required) the first parameter is a string indicating the path of your endpoint. For example, if you have custom endpoints that begin with /admin/vendorsCopy to Clipboard, the value of this parameter would be vendorsCopy to Clipboard. The /adminCopy to Clipboard prefix will be added automatically.
2. queryKeyCopy to Clipboard: (required) the second parameter is a string used to generate query keys, which are used by Tanstack Query for caching. When a mutation related to this same key succeeds, the key will be automatically invalidated.
3. queryCopy to Clipboard: (optional) the third parameter is an object that can be used to pass query parameters to the endpoint. For example, if you want to pass an expandCopy to Clipboard query parameter you can pass it within this object. Each query parameter's name is a key in the object. There are no limitations on what the type of the value can be, so you can pass an array or simply a string as a value.
4. optionsCopy to Clipboard: (optional) the fourth parameter is an object of TanStack Query options.

The request returns an object containing keys like dataCopy to Clipboard which is an object that includes the data returned in the response, and isLoadingCopy to Clipboard which is a boolean value indicating whether the request is still in progress. You can learn more about the returned object's properties in TanStack Query's documentation.

For example:

• src/admin/routes/blog/posts/[id]/page.tsx
• src/admin/routes/blog/author/[id]/posts/page.tsx

import { useAdminCustomQuery } from "medusa-react"
import { useParams } from "react-router-dom"

type BlogPost = {
  title: string,
  content: string,
  author_id: string,
}

// Single post
type AdminBlogPostQuery = {
  expand?: string,
  fields?: string
}

type AdminBlogPostRes = {
  post: BlogPost,
}

const BlogPost = () => {
  const { id } = useParams() 

  const { data: { post }, isLoading } = useAdminCustomQuery<
    AdminBlogPostQuery,
    AdminBlogPostRes
  >(
    `/blog/posts/${id}`,  // path
    ["blog-post", id], // queryKey
    {
      expand: "author", // query
    }
   )

  return (
    <>
      {isLoading && <span>Loading...</span>}
      {post && <span>{post.title}</span>}
    </>
  )
}

export default BlogPost

Report Incorrect CodeCopy to Clipboard

import { useAdminCustomQuery } from "medusa-react"
import { useParams } from "react-router-dom"

type BlogPost = {
  title: string,
  content: string,
  author_id: string,
}

type AdminBlogPostsRes = {
  posts: BlogPost[],
  count: number
}

type AdminBlogPostsQuery = {
  author_id: string,
  created_at?: string,
  expand?: string,
  fields?: string
}

const AuthorsBlogPosts = () => {
  const { id } = useParams() 

  const { data: { posts }, isLoading } = useAdminCustomQuery<
    AdminBlogPostsQuery, AdminBlogPostsRes
  >(
    `/blog/posts`,  // path
    ["blog-posts", "list", id], // queryKey
    {
      expand: "author", // query
      author_id: "auth_123",
    }
   )

   return (
     <>
       {isLoading && <span>Loading...</span>}
       {posts && <span>{posts.map((post, index) => (
        <span key={index}>{post.title}</span>
       ))}</span>}
     </>
   )
}

export default AuthorsBlogPosts

Report Incorrect CodeCopy to Clipboard

useAdminCustomPost

The useAdminCustomPostCopy to Clipboard utility hook can be used to send a POSTCopy to Clipboard request to a custom endpoint in your Medusa backend. It's a generic function, so you can pass a type for the request and the response if you're using TypeScript in your development. The first type parameter is the type of the request body, and the second type parameter is the type of the expected response body:

useAdminCustomPost<RequestType, ResponseType>

Report Incorrect CodeCopy to Clipboard

The hook accepts the following parameters:

1. pathCopy to Clipboard: (required) the first parameter is a string indicating the path of your endpoint. For example, if you have custom endpoints that begin with /admin/vendorsCopy to Clipboard, the value of this parameter would be vendorsCopy to Clipboard. The /adminCopy to Clipboard prefix will be added automatically.
2. queryKeyCopy to Clipboard: (required) the second parameter is a string used to generate query keys, which are used by Tanstack Query for caching. When the mutation succeeds, the key will be automatically invalidated.
3. relatedDomainsCopy to Clipboard: (optional) the third parameter is an object that can be used to specify domains related to this custom hook. This will ensure that Tanstack Query invalides the keys for those domains when your custom mutations succeed. For example, if your custom endpoint is related to products, you can pass ["products"]Copy to Clipboard as the value of this parameter. Then, when you use your custom mutation and it succeeds, the product's key adminProductKeys.allCopy to Clipboard will be invalidated automatically, and all products will be re-fetched.
4. optionsCopy to Clipboard: (optional) the fourth parameter is an object of Mutation options.

The request returns an object containing keys like mutationCopy to Clipboard which is a function that can be used to send the POSTCopy to Clipboard request at a later point. You can learn more about the returned object's properties in TanStack Query's documentation.

For example:

src/admin/routes/blog/posts/page.tsx

import { useAdminCustomPost } from "medusa-react"
import { useNavigate } from "react-router-dom"

type BlogPost = {
  id: string
  title: string,
  content: string,
  author_id: string,
}

type AdminBlogPostReq = {
  title: string,
  content: string,
  author_id: string,
}

type AdminBlogPostRes = {
  post: BlogPost,
}

const CreateBlogPost = () => {
  const navigate = useNavigate() 

  const { mutate, isLoading } = useAdminCustomPost<
    AdminBlogPostReq,
    AdminBlogPostRes
  >(
    `/blog/posts`,
    ["blog-posts"],
    {
      product: true,
    }
   )

  const handleCreate = (args: AdminBlogPostReq) => {
    return mutate(args, {
      onSuccess: (data) => {
        navigate(`blog/posts/${data.post.id}`)
      },
    })
  }

  // TODO replace with actual form
  return (
    <button
      onClick={() => handleCreate({
        title: "First Blog Post",
        content: "Blog Content",
        author_id: "auth_123",
      })}>
        Create
    </button>
  )
}

export default CreateBlogPost

Report Incorrect CodeCopy to Clipboard

useAdminCustomDelete

The useAdminCustomDeleteCopy to Clipboard utility hook can be used to send a DELETECopy to Clipboard request to a custom endpoint in your Medusa backend. It's a generic function, so you can pass a type for the request body if you're using TypeScript in your development:

useAdminCustomPost<RequestType, ResponseType>

Report Incorrect CodeCopy to Clipboard

The hook accepts the following parameters:

1. pathCopy to Clipboard: (required) the first parameter is a string indicating the path of your endpoint. For example, if you have custom endpoints that begin with /admin/vendorsCopy to Clipboard, the value of this parameter would be vendorsCopy to Clipboard. The /adminCopy to Clipboard prefix will be added automatically.
2. queryKeyCopy to Clipboard: (required) the second parameter is a string used to generate query keys, which are used by Tanstack Query for caching. When the mutation succeeds, the key will be automatically invalidated.
3. relatedDomainsCopy to Clipboard: (optional) the third parameter is an object that can be used to specify domains related to this custom hook. This will ensure that Tanstack Query invalides the keys for those domains when your custom mutations succeed. For example, if your custom endpoint is related to products, you can pass ["products"]Copy to Clipboard as the value of this parameter. Then, when you use your custom mutation and it succeeds, the product's key adminProductKeys.allCopy to Clipboard will be invalidated automatically, and all products will be re-fetched.
4. optionsCopy to Clipboard: (optional) the fourth parameter is an object of Mutation options.

The request returns an object containing keys like mutationCopy to Clipboard which is a function that can be used to send the DELETECopy to Clipboard request at a later point. You can learn more about the returned object's properties in TanStack Query's documentation.

For example:

src/admin/routes/blog/posts/[id]/page.tsx

import { useAdminCustomDelete } from "medusa-react"
import { useNavigate, useParams } from "react-router-dom"

type AdminBlogPostDeleteRes = {
  id: string,
  type: string
}

const BlogPost = () => {
  const { id } = useParams()
  const navigate = useNavigate() 

  const { mutate, isLoading } = useAdminCustomDelete<
    AdminBlogPostDeleteRes
  >(
    `/blog/posts/${id}`,
    ["blog-posts"],
    {
      product: true,
    }
   )

  const handleDelete = () => {
    return mutate(undefined, {
      onSuccess: () => {
        navigate("..")
      },
    })
  }

  // TODO replace with actual form
  return (
    <button
      onClick={() => handleDelete()}>
        Delete
    </button>
  )
}

export default BlogPost

Report Incorrect CodeCopy to Clipboard

---

Utilities

medusa-reactCopy to Clipboard exposes a set of utility functions that are mainly used to retrieve or format the price of a product variant.

formatVariantPrice

This utility function can be used to compute the price of a variant for a region and retrieve the formatted amount. For example, $20.00Copy to Clipboard.

It accepts an object with the following properties:

• variantCopy to Clipboard: A variant object retrieved from the Medusa backend. It should mainly include the pricesCopy to Clipboard array in the object.
• regionCopy to Clipboard: A region object retrieved from the Medusa backend.
• includeTaxesCopy to Clipboard: (optional) A boolean value that indicates whether the computed price should include taxes or not. The default value is trueCopy to Clipboard.
• minimumFractionDigitsCopy to Clipboard: (optional) The minimum number of fraction digits to use when formatting the price. This is passed as an option to Intl.NumberFormatCopy to Clipboard in the underlying layer. You can learn more about this method’s options in MDN’s documentation.
• maximumFractionDigitsCopy to Clipboard: (optional) The maximum number of fraction digits to use when formatting the price. This is passed as an option to Intl.NumberFormatCopy to Clipboard which is used within the utility method. You can learn more about this method’s options in MDN’s documentation.
• localeCopy to Clipboard: (optional) A string with a BCP 47 language tag. The default value is en-USCopy to Clipboard. This is passed as a first parameter to Intl.NumberFormatCopy to Clipboard which is used within the utility method. You can learn more about this method’s parameters in MDN’s documentation.

For example:

src/Products.ts

import { formatVariantPrice } from "medusa-react"
import { Product, ProductVariant } from "@medusajs/medusa"

const Products = () => {
  // ...
  return (
    <ul>
      {products?.map((product: Product) => (
        <li key={product.id}>
          {product.title}
          <ul>
            {product.variants.map((variant: ProductVariant) => (
              <li key={variant.id}>
                {formatVariantPrice({
                  variant,
                  region, // should be retrieved earlier
                })}
              </li>
            ))}
          </ul>
        </li>
      ))}
    </ul>
  )
}

Report Incorrect CodeCopy to Clipboard

computeVariantPrice

This utility function can be used to compute the price of a variant for a region and retrieve the amount without formatting. For example, 20Copy to Clipboard. This method is used by formatVariantPriceCopy to Clipboard before applying the price formatting.

It accepts an object with the following properties:

• variantCopy to Clipboard: A variant object retrieved from the Medusa backend. It should mainly include the pricesCopy to Clipboard array in the variant.
• regionCopy to Clipboard: A region object retrieved from the Medusa backend.
• includeTaxesCopy to Clipboard: (optional) A boolean value that indicates whether the computed price should include taxes or not. The default value is trueCopy to Clipboard.

For example:

src/Products.ts

import { computeVariantPrice } from "medusa-react"
import { Product, ProductVariant } from "@medusajs/medusa"

const Products = () => {
  // ...
  return (
    <ul>
      {products?.map((product: Product) => (
        <li key={product.id}>
          {product.title}
          <ul>
            {product.variants.map((variant: ProductVariant) => (
              <li key={variant.id}>
                {computeVariantPrice({
                  variant,
                  region, // should be retrieved earlier
                })}
              </li>
            ))}
          </ul>
        </li>
      ))}
    </ul>
  )
}

Report Incorrect CodeCopy to Clipboard

formatAmount

This utility function can be used to compute the price of an amount for a region and retrieve the formatted amount. For example, $20.00Copy to Clipboard.

The main difference between this utility function and formatVariantPriceCopy to Clipboard is that you don’t need to pass a complete variant object. This can be used with any number.

It accepts an object with the following properties:

• amountCopy to Clipboard: A number that should be used for computation.
• regionCopy to Clipboard: A region object retrieved from the Medusa backend.
• includeTaxesCopy to Clipboard: (optional) A boolean value that indicates whether the computed price should include taxes or not. The default value is trueCopy to Clipboard.
• minimumFractionDigitsCopy to Clipboard: (optional) The minimum number of fraction digits to use when formatting the price. This is passed as an option to Intl.NumberFormatCopy to Clipboard in the underlying layer. You can learn more about this method’s options in MDN’s documentation.
• maximumFractionDigitsCopy to Clipboard: (optional) The maximum number of fraction digits to use when formatting the price. This is passed as an option to Intl.NumberFormatCopy to Clipboard which is used within the utility method. You can learn more about this method’s options in MDN’s documentation.
• localeCopy to Clipboard: (optional) A string with a BCP 47 language tag. The default value is en-USCopy to Clipboard. This is passed as a first parameter to Intl.NumberFormatCopy to Clipboard which is used within the utility method. You can learn more about this method’s parameters in MDN’s documentation.

For example:

src/MyComponent.ts

import { formatAmount } from "medusa-react"

const MyComponent = () => {
  // ...
  return (
    <div>
      {formatAmount({
        amount,
        region, // should be retrieved earlier
      })}
    </div>
  )
}

Report Incorrect CodeCopy to Clipboard

computeAmount

This utility function can be used to compute the price of an amount for a region and retrieve the amount without formatting. For example, 20Copy to Clipboard. This method is used by formatAmountCopy to Clipboard before applying the price formatting.

The main difference between this utility function and computeVariantPriceCopy to Clipboard is that you don’t need to pass a complete variant object. This can be used with any number.

It accepts an object with the following properties:

• amountCopy to Clipboard: A number that should be used for computation.
• regionCopy to Clipboard: A region object retrieved from the Medusa backend.
• includeTaxesCopy to Clipboard: (optional) A boolean value that indicates whether the computed price should include taxes or not. The default value is trueCopy to Clipboard.

For example:

src/MyComponent.ts

import { computeAmount } from "medusa-react"

const MyComponent = () => {
  // ...
  return (
    <div>
      {computeAmount({
        amount,
        region, // should be retrieved earlier
      })}
    </div>
  )
}

Report Incorrect CodeCopy to Clipboard

---

Content Providers

This is an experimental feature.

To facilitate building custom storefronts, medusa-reactCopy to Clipboard also exposes a CartProviderCopy to Clipboard and a SessionCartProviderCopy to Clipboard.

CartProvider

CartProviderCopy to Clipboard makes use of some of the hooks already exposed by medusa-reactCopy to Clipboard 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 CartProviderCopy to Clipboard, you first have to insert it somewhere in your component tree below the MedusaProviderCopy to Clipboard.

For 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

Report Incorrect CodeCopy to Clipboard

Then, in any of the child components, you can use the useCartCopy to Clipboard hook exposed by medusa-reactCopy to Clipboard to get access to cart operations and data.

The useCartCopy to Clipboard hook returns an object with the following properties:

• cartCopy to Clipboard: A state variable holding the cart object. This is set if the createCartCopy to Clipboard mutation is executed or if setCartCopy to Clipboard is manually used.
• setCartCopy to Clipboard: A state function used to set the cart object.
• totalItemsCopy to Clipboard: The number of items in the cart.
• createCartCopy to Clipboard: A mutation used to create a cart.
• updateCartCopy to Clipboard: A mutation used to update a cart’s details such as region, customer email, shipping address, and more.
• startCheckoutCopy to Clipboard: A mutation used to initialize payment sessions during checkout.
• payCopy to Clipboard: A mutation used to select a payment processor during checkout.
• addShippingMethodCopy to Clipboard: A mutation used to add a shipping method to the cart during checkout.
• completeCheckoutCopy to Clipboard: A mutation used to complete the cart and place the order.

For 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

Report Incorrect CodeCopy to Clipboard

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

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

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.

SessionProvider

Unlike the CartProviderCopy to Clipboard, SessionProviderCopy to Clipboard never interacts with the Medusa backend. It can be used to implement the user experience related to managing a cart’s items. Its state variables are JavaScript objects living in the browser, but are in no way communicated with the backend.

You can use the SessionProviderCopy to Clipboard as a lightweight client-side cart functionality. It’s not stored in any database or on the Medusa backend.

To use SessionProviderCopy to Clipboard, you first have to insert it somewhere in your component tree below the MedusaProviderCopy to Clipboard.

For example:

src/App.ts

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

const queryClient = new QueryClient()

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

export default App

Report Incorrect CodeCopy to Clipboard

Then, in any of the child components, you can use the useSessionHookCopy to Clipboard hook exposed by medusa-reactCopy to Clipboard to get access to client-side cart item functionalities.

For example:

src/Products.ts

const Products = () => {
  const { addItem } = useSessionCart()
  // ...

  function addToCart(variant: ProductVariant) {
    addItem({
      variant: variant,
      quantity: 1,
    })
  }
}

Report Incorrect CodeCopy to Clipboard