use-shopping-cart logouse-shopping-cart
Configuration

storage

Configure custom storage adapters for cart persistence.

Type

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.

Default

createLocalStorage() - Uses browser's localStorage

Usage

Default (LocalStorage)

<CartProvider
  currency="USD"
  // Uses localStorage by default
>
  <App />
</CartProvider>

SessionStorage

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

export const Root = () => (
  <CartProvider currency="USD" storage={createSessionStorage()}>
    <App />
  </CartProvider>
)

Memory Storage

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

export const Root = () => (
  <CartProvider currency="USD" storage={createMemoryStorage()}>
    <App />
  </CartProvider>
)

No Storage

export const Root = () => (
  <CartProvider currency="USD" shouldPersist={false}>
    <App />
  </CartProvider>
)

Built-in Adapters

createLocalStorage() (Default)

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

<CartProvider storage={createLocalStorage()}>
  <App />
</CartProvider>
  • Persists across browser sessions
  • ~5-10MB storage limit
  • Synchronous API
  • Used by default if no storage specified

createSessionStorage()

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

<CartProvider storage={createSessionStorage()}>
  <App />
</CartProvider>
  • Clears when the tab closes
  • ~5-10MB storage limit
  • Synchronous API
  • Per-tab storage
  • Good for temporary shopping sessions

Custom Storage Adapter

Example: Async Storage (React Native)

import AsyncStorage from '@react-native-async-storage/async-storage'

const asyncStorageAdapter = {
  getItem: (key) => {
    return AsyncStorage.getItem(key)
  },
  setItem: (key, value) => {
    return AsyncStorage.setItem(key, value)
  },
  removeItem: (key) => {
    return AsyncStorage.removeItem(key)
  }
}

<CartProvider storage={asyncStorageAdapter}>
  <App />
</CartProvider>

Example: Server Sync

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

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

    // Then sync to server (fire and forget)
    fetch('/api/save-cart', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ key, value })
    }).catch(console.error)
  },

  removeItem(key) {
    localStorage.removeItem(key)

    fetch('/api/clear-cart', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ key })
    }).catch(console.error)
  }
}

<CartProvider storage={serverSyncStorage} />

Example: Compressed Storage

import LZString from 'lz-string'

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

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

  removeItem(key) {
    localStorage.removeItem(key)
  }
}

<CartProvider storage={compressedStorage} />

Example: IndexedDB

import { openDB } from 'idb'

const dbPromise = openDB('cart-db', 1, {
  upgrade(db) {
    db.createObjectStore('cart')
  }
})

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

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

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

<CartProvider storage={indexedDBStorage} />

Notes

  • setItem is called when the cart entries, currency or language change, once for changes made together in the same task. With an async adapter, changes made while the saved cart loads are written once the load finishes
  • Must implement all three methods: getItem, setItem, removeItem
  • Methods can be async (return Promises)
  • Values are always strings (serialized JSON)
  • Handle errors gracefully to prevent cart crashes
  • SSR is handled automatically (no special storage needed)

See Also

On this page

Shopping Cart

Your cart is empty

Try the interactive demos on the docs pages!