use-shopping-cart logouse-shopping-cart
Components

CartProvider

The <CartProvider /> component wraps your app and provides cart state and methods to all child components via the useShoppingCart() hook.

At the root level of your app, wrap your Root app in the <CartProvider />

Basic Example

import { createRoot } from 'react-dom/client'
import { CartProvider } from 'use-shopping-cart'
import App from './App'

createRoot(document.getElementById('root')).render(
  <CartProvider currency="USD">
    <App />
  </CartProvider>
)

With Custom Persistence Settings

import { createRoot } from 'react-dom/client'
import { CartProvider } from 'use-shopping-cart'
import App from './App'

createRoot(document.getElementById('root')).render(
  <CartProvider
    currency="USD"
    // Optional: Customize cart persistence
    shouldPersist={true} // Enable persistence (default: true)
    persistKey="my-custom-cart" // Custom localStorage key (default: 'use-shopping-cart')
  >
    <App />
  </CartProvider>
)

Your product object must adhere to the following shape:

const products = [
  {
    // Line item name to be shown on the Stripe Checkout page
    name: 'Bananas',
    // Optional description to be shown on the Stripe Checkout page
    description: 'Yummy yellow fruit',
    // A unique identifier for this item
    id: 'id_banana001',
    // price in smallest currency unit (e.g. cent for USD)
    price: 400,
    currency: 'USD',
    // Optional image to be shown on the Stripe Checkout page
    image:
      'https://images.unsplash.com/photo-1571771894821-ce9b6c11b08e?w=400&h=400&fit=crop&q=80'
  }
]

Additionally, you must verify the cartItems on the server-side before creating the CheckoutSession. For this you can use the validateCartItems() helper.

Complete Props Reference

PropTypeRequiredDefaultDescription
currencystringNo'USD'ISO currency code (e.g., 'USD', 'EUR', 'GBP')
languagestringNoBrowser languageLanguage for currency formatting (e.g., 'en-US', 'fr-FR')
shouldPersistbooleanNotrueEnable cart persistence in localStorage
persistKeystringNo'use-shopping-cart'localStorage key name for cart data
storageStorageAdapterNolocalStorageCustom storage adapter for persistence
cartDetailsCartDetailsInputNo{}Initial cart entries; totals are computed from them

Props Are Read Once

CartProvider creates its cart when it mounts and ignores later changes to these props. Change the currency or language with changeCurrency and changeLanguage. To start a different cart, for example when a shopper signs in, give CartProvider a new key; this remounts everything inside it:

<CartProvider key={userId} persistKey={`cart-${userId}`}>
  <App />
</CartProvider>

Server Rendering

CartProvider renders its children on the server (Next.js, Remix, TanStack Start). The server and the first client render show the cart from your props: cartDetails (empty by default), formatted with language (en-US if you don't set one). Right after hydration, the cart saved in storage and the browser's language take over, so there's no hydration mismatch. Set language if you want server-rendered prices formatted for a specific language.

Configuring Checkout Features

Modern Stripe features (phone collection, promotion codes, automatic tax, custom fields, shipping options, etc.) should be configured server-side when creating the checkout session in your endpoint.

Example:

// In your server endpoint
const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items,
  success_url: `${origin}/success`,
  cancel_url: origin,

  // Configure all Stripe features here
  phone_number_collection: { enabled: true },
  allow_promotion_codes: true,
  automatic_tax: { enabled: true }
})

See Stripe's Checkout Session API for all available options.

Client-only Checkout Mode (Removed)

⚠️ REMOVED: Client-only mode has been removed in v4.0. Please use checkout-session mode.

See the migration guide for help upgrading.

On this page

Shopping Cart

Your cart is empty

Try the interactive demos on the docs pages!