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
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
currency | string | No | 'USD' | ISO currency code (e.g., 'USD', 'EUR', 'GBP') |
language | string | No | Browser language | Language for currency formatting (e.g., 'en-US', 'fr-FR') |
shouldPersist | boolean | No | true | Enable cart persistence in localStorage |
persistKey | string | No | 'use-shopping-cart' | localStorage key name for cart data |
storage | StorageAdapter | No | localStorage | Custom storage adapter for persistence |
cartDetails | CartDetailsInput | No | {} | 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.
