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 restoredConfiguration
<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:
shouldPersistisn'tfalse- Storage is available (some browsers block it, for example with all cookies disabled)
- Storage quota not exceeded
- No localStorage errors in console
Cart Clearing on Refresh
Check:
- Using localStorage, not sessionStorage
- Not calling
clearCart()on mount - persistKey is consistent
- 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
- ShoppingCart Class - Core class
- shouldPersist - Enable/disable persistence
- persistKey - Custom storage key
- loadCart - Load cart manually
