use-shopping-cart logouse-shopping-cart
Concepts

Cart Persistence

How cart data is saved and restored across sessions.

Overview

Cart persistence ensures customers don't lose their cart when they:

  • Refresh the page
  • Close and reopen the browser
  • Navigate between pages
  • Return to your site later

How It Works

Auto-Save

Every cart change is automatically saved:

User adds item
      ↓
Cart state updates
      ↓
State serialized to JSON
      ↓
Saved to storage
      ↓
User refreshes page
      ↓
State loaded from storage
      ↓
Cart restored

Configuration

<CartProvider
  currency="USD"
  shouldPersist={true} // Enable persistence (default)
  persistKey="my-shopping-cart" // Storage key (optional)
>
  <App />
</CartProvider>

Storage Adapters

LocalStorage (Default)

Saves to browser's localStorage:

<CartProvider
  shouldPersist={true}
  // Uses localStorage by default
>
  <App />
</CartProvider>

Pros:

  • Persists across sessions
  • Available in all browsers
  • ~5-10MB storage limit

Cons:

  • Cleared when an incognito window closes
  • Synchronous (can block)
  • Not shared across tabs automatically

SessionStorage

Clears when the tab closes:

import { createSessionStorage } from 'use-shopping-cart/core'

export const Root = () => (
  <CartProvider shouldPersist={true} storage={createSessionStorage()}>
    <App />
  </CartProvider>
)

Use when:

  • Cart should clear when the tab closes
  • Temporary shopping sessions
  • Multi-tab isolation needed

Memory Storage

Keeps the cart in memory for the life of the page (useful in tests):

import { createMemoryStorage } from 'use-shopping-cart/core'

export const Root = () => (
  <CartProvider shouldPersist={true} storage={createMemoryStorage()}>
    <App />
  </CartProvider>
)

Use when:

  • Testing
  • You want a cart that survives client-side navigation but not a reload

No Storage

Disable persistence completely:

<CartProvider shouldPersist={false}>
  <App />
</CartProvider>

Custom Storage

Interface

interface StorageAdapter {
  getItem(key: string): Promise<string | null> | string | null
  setItem(key: string, value: string): Promise<void> | void
  removeItem(key: string): Promise<void> | void
}

StorageAdapter is exported from use-shopping-cart and use-shopping-cart/core. Each method can return its result directly or as a Promise.

Example: IndexedDB

const indexedDBStorage = {
  async getItem(key) {
    const db = await openDB()
    return db.get('cart', key)
  },

  async setItem(key, value) {
    const db = await openDB()
    await db.put('cart', value, key)
  },

  async removeItem(key) {
    const db = await openDB()
    await db.delete('cart', key)
  }
}

<CartProvider storage={indexedDBStorage} />

Example: Server Sync

const serverSyncStorage = {
  getItem(key) {
    // Load from localStorage as fallback
    return localStorage.getItem(key)
  },

  setItem(key, value) {
    // Save locally
    localStorage.setItem(key, value)

    // Sync to server
    fetch('/api/save-cart', {
      method: 'POST',
      body: JSON.stringify({ cart: value })
    })
  },

  removeItem(key) {
    localStorage.removeItem(key)
    fetch('/api/clear-cart', { method: 'POST' })
  }
}

<CartProvider storage={serverSyncStorage} />

Storage Key

Customize the localStorage key name for multiple carts or to avoid conflicts:

// Main cart - stores in localStorage under 'main-cart'
<CartProvider persistKey="main-cart">
  <MainShop />
</CartProvider>

// Gift cart - stores in localStorage under 'gift-cart'
<CartProvider persistKey="gift-cart">
  <GiftShop />
</CartProvider>

Note: The persistKey is used directly as the localStorage key name. There's no prefix or transformation applied.

What Gets Stored

Only cart-specific data is persisted to localStorage:

{
  cartDetails: { /* all cart entries */ },
  cartCount: number,
  totalPrice: number,
  formattedTotalPrice: string,
  currency: string,
  language: string
}

Configuration settings (persistKey, storage, shouldPersist) are NOT stored - only cart state and formatting context.

Data Format

Serialized State

The cart data is stored as JSON in localStorage:

{
  "cartCount": 3,
  "totalPrice": 1200,
  "formattedTotalPrice": "$12.00",
  "currency": "USD",
  "language": "en-US",
  "cartDetails": {
    "banana_001": {
      "id": "banana_001",
      "name": "Bananas",
      "price": 400,
      "currency": "USD",
      "quantity": 2,
      "value": 800
    },
    "apple_001": {
      "id": "apple_001",
      "name": "Apples",
      "price": 400,
      "currency": "USD",
      "quantity": 1,
      "value": 400
    }
  }
}

Cross-Tab Sync

By default, changes in one tab don't automatically sync to other tabs. You can enable cross-tab sync:

import { useEffect } from 'react'
import { useShoppingCart } from 'use-shopping-cart'

function CrossTabSync() {
  const { loadCart, changeCurrency, changeLanguage } = useShoppingCart()

  useEffect(() => {
    // Listen for storage changes from other tabs
    const handleStorage = (e) => {
      // Check if it's our cart key
      if (e.key !== 'use-shopping-cart') return
      // Read the latest saved cart, not e.newValue
      const latest = localStorage.getItem('use-shopping-cart')
      if (!latest) return
      const cart = JSON.parse(latest)
      changeCurrency(cart.currency)
      changeLanguage(cart.language)
      loadCart(cart.cartDetails, false)
    }

    window.addEventListener('storage', handleStorage)
    return () => window.removeEventListener('storage', handleStorage)
  }, [loadCart, changeCurrency, changeLanguage])

  return null
}

Note: The storage event only fires in OTHER tabs, not the current tab. Pass false to loadCart so the other tab's cart replaces this one; merging would keep cart entries the other tab removed. Take the other tab's currency and language too: if the tabs format prices differently, each saves its own version back and they update each other forever. Read the latest saved cart instead of e.newValue: when the other tab changes the cart several times quickly, events arrive after newer changes, and applying an old one would save that older cart back over the newer one. The cart doesn't save what storage already holds, so applying the latest saved cart doesn't echo it back. If using a custom persistKey, check for that key instead of 'use-shopping-cart'.

Manual Control

Save Manually

const { cartDetails } = useShoppingCart()

const handleSave = () => {
  localStorage.setItem('backup-cart', JSON.stringify(cartDetails))
}

Load Manually

const { loadCart } = useShoppingCart()

const handleRestore = () => {
  const backup = localStorage.getItem('backup-cart')
  if (backup) {
    loadCart(JSON.parse(backup))
  }
}

Clear Storage

const { clearCart } = useShoppingCart()

const handleClearEverything = () => {
  clearCart() // Clears cart state
  localStorage.removeItem('use-shopping-cart') // Clears storage
}

Best Practices

1. Handle Corrupted Data

The cart already ignores a saved cart it can't parse. To also delete it, check it in your adapter's getItem, which must return the stored string (not parsed JSON):

const customStorage = {
  getItem(key) {
    const value = localStorage.getItem(key)
    try {
      if (value) JSON.parse(value)
      return value
    } catch (error) {
      console.error('Corrupted cart data, clearing:', error)
      localStorage.removeItem(key)
      return null
    }
  },
  setItem: (key, value) => localStorage.setItem(key, value),
  removeItem: (key) => localStorage.removeItem(key)
}

2. Expire Old Carts

const EXPIRY_DAYS = 30

const timestampedStorage = {
  setItem(key, value) {
    const data = {
      value,
      timestamp: Date.now()
    }
    localStorage.setItem(key, JSON.stringify(data))
  },

  getItem(key) {
    const item = localStorage.getItem(key)
    if (!item) return null

    const { value, timestamp } = JSON.parse(item)
    const age = Date.now() - timestamp
    const maxAge = EXPIRY_DAYS * 24 * 60 * 60 * 1000

    if (age > maxAge) {
      localStorage.removeItem(key)
      return null
    }

    return value
  },

  removeItem: (key) => localStorage.removeItem(key)
}

3. Compress Large Carts

import { compress, decompress } from 'lz-string'

const compressedStorage = {
  setItem(key, value) {
    const compressed = compress(value)
    localStorage.setItem(key, compressed)
  },

  getItem(key) {
    const compressed = localStorage.getItem(key)
    return compressed ? decompress(compressed) : null
  },

  removeItem: (key) => localStorage.removeItem(key)
}

Troubleshooting

Cart Not Persisting

Check:

  1. shouldPersist isn't false
  2. Storage is available (some browsers block it, for example with all cookies disabled)
  3. Storage quota not exceeded
  4. No localStorage errors in console

Cart Clearing on Refresh

Check:

  1. Using localStorage, not sessionStorage
  2. Not calling clearCart() on mount
  3. persistKey is consistent
  4. No browser extensions clearing storage

Data Loss

Implement backup strategy:

function BackupCart() {
  const cartDetails = useShoppingCart((cart) => cart.cartDetails)

  useEffect(() => {
    if (Object.keys(cartDetails).length === 0) return

    const timeout = setTimeout(() => {
      fetch('/api/backup-cart', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ cart: cartDetails })
      })
    }, 2000)

    return () => clearTimeout(timeout)
  }, [cartDetails])

  return null
}

See Also

On this page

Shopping Cart

Your cart is empty

Try the interactive demos on the docs pages!