📄 tanstack/db/latest/docs/reference/functions/localStorageCollectionOptions

function localStorageCollectionOptions<T, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, LocalStorageCollectionUtils> & object;


function localStorageCollectionOptions<T, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, LocalStorageCollectionUtils> & object;

Defined in: packages/db/src/local-storage.ts:279

Creates localStorage collection options for use with a standard Collection

This function creates a collection that persists data to localStorage/sessionStorage and synchronizes changes across browser tabs using storage events.

Fallback Behavior:

When localStorage is not available (e.g., in server-side rendering environments), this function automatically falls back to an in-memory storage implementation. This prevents errors during module initialization and allows the collection to work in any environment, though data will not persist across page reloads or be shared across tabs when using the in-memory fallback.

Using with Manual Transactions:

For manual transactions, you must call utils.acceptMutations() in your transaction's mutationFn to persist changes made during tx.mutate(). This is necessary because local-storage collections don't participate in the standard mutation handler flow for manual transactions.

### Type Parameters #### T

T extends StandardSchemaV1<unknown, unknown>

#### TKey

TKey extends string | number = string | number

### Parameters #### config

LocalStorageCollectionConfig <InferSchemaOutput <T>, T, TKey> & object

Configuration options for the localStorage collection

### Returns

CollectionConfig <InferSchemaOutput <T>, TKey, T, LocalStorageCollectionUtils > & object

Collection options with utilities including clearStorage, getStorageSize, and acceptMutations

### Examples

// Basic localStorage collection
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    getKey: (item) => item.id,
  })
)


// Basic localStorage collection
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    getKey: (item) => item.id,
  })
)

// localStorage collection with custom storage
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    storage: window.sessionStorage, // Use sessionStorage instead
    getKey: (item) => item.id,
  })
)


// localStorage collection with custom storage
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    storage: window.sessionStorage, // Use sessionStorage instead
    getKey: (item) => item.id,
  })
)

// localStorage collection with mutation handlers
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      console.log('Item inserted:', transaction.mutations[0].modified)
    },
  })
)


// localStorage collection with mutation handlers
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      console.log('Item inserted:', transaction.mutations[0].modified)
    },
  })
)

// Using with manual transactions
const localSettings = createCollection(
  localStorageCollectionOptions({
    storageKey: 'user-settings',
    getKey: (item) => item.id,
  })
)

const tx = createTransaction({
  mutationFn: async ({ transaction }) => {
    // Use settings data in API call
    const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)
    await api.updateUserProfile({ settings: settingsMutations[0]?.modified })

    // Persist local-storage mutations after API success
    localSettings.utils.acceptMutations(transaction)
  }
})

tx.mutate(() => {
  localSettings.insert({ id: 'theme', value: 'dark' })
  apiCollection.insert({ id: 2, data: 'profile data' })
})

await tx.commit()


// Using with manual transactions
const localSettings = createCollection(
  localStorageCollectionOptions({
    storageKey: 'user-settings',
    getKey: (item) => item.id,
  })
)

const tx = createTransaction({
  mutationFn: async ({ transaction }) => {
    // Use settings data in API call
    const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)
    await api.updateUserProfile({ settings: settingsMutations[0]?.modified })

    // Persist local-storage mutations after API success
    localSettings.utils.acceptMutations(transaction)
  }
})

tx.mutate(() => {
  localSettings.insert({ id: 'theme', value: 'dark' })
  apiCollection.insert({ id: 2, data: 'profile data' })
})

await tx.commit()

Call Signature
--------------

function localStorageCollectionOptions<T, TKey>(config): CollectionConfig<T, TKey, never, LocalStorageCollectionUtils> & object;


function localStorageCollectionOptions<T, TKey>(config): CollectionConfig<T, TKey, never, LocalStorageCollectionUtils> & object;

Defined in: packages/db/src/local-storage.ts:299

Creates localStorage collection options for use with a standard Collection

This function creates a collection that persists data to localStorage/sessionStorage and synchronizes changes across browser tabs using storage events.

Fallback Behavior:

Using with Manual Transactions:

### Type Parameters #### T

T extends object

#### TKey

TKey extends string | number = string | number

### Parameters #### config

LocalStorageCollectionConfig <T, never, TKey> & object

Configuration options for the localStorage collection

### Returns

CollectionConfig <T, TKey, never, LocalStorageCollectionUtils > & object

Collection options with utilities including clearStorage, getStorageSize, and acceptMutations

### Examples

// Basic localStorage collection
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    getKey: (item) => item.id,
  })
)


// Basic localStorage collection
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    getKey: (item) => item.id,
  })
)

// localStorage collection with custom storage
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    storage: window.sessionStorage, // Use sessionStorage instead
    getKey: (item) => item.id,
  })
)


// localStorage collection with custom storage
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    storage: window.sessionStorage, // Use sessionStorage instead
    getKey: (item) => item.id,
  })
)

// localStorage collection with mutation handlers
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      console.log('Item inserted:', transaction.mutations[0].modified)
    },
  })
)


// localStorage collection with mutation handlers
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      console.log('Item inserted:', transaction.mutations[0].modified)
    },
  })
)

// Using with manual transactions
const localSettings = createCollection(
  localStorageCollectionOptions({
    storageKey: 'user-settings',
    getKey: (item) => item.id,
  })
)

const tx = createTransaction({
  mutationFn: async ({ transaction }) => {
    // Use settings data in API call
    const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)
    await api.updateUserProfile({ settings: settingsMutations[0]?.modified })

    // Persist local-storage mutations after API success
    localSettings.utils.acceptMutations(transaction)
  }
})

tx.mutate(() => {
  localSettings.insert({ id: 'theme', value: 'dark' })
  apiCollection.insert({ id: 2, data: 'profile data' })
})

await tx.commit()


// Using with manual transactions
const localSettings = createCollection(
  localStorageCollectionOptions({
    storageKey: 'user-settings',
    getKey: (item) => item.id,
  })
)

const tx = createTransaction({
  mutationFn: async ({ transaction }) => {
    // Use settings data in API call
    const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)
    await api.updateUserProfile({ settings: settingsMutations[0]?.modified })

    // Persist local-storage mutations after API success
    localSettings.utils.acceptMutations(transaction)
  }
})

tx.mutate(() => {
  localSettings.insert({ id: 'theme', value: 'dark' })
  apiCollection.insert({ id: 2, data: 'profile data' })
})

await tx.commit()

Edit on GitHub

Home

Partners Become a Partner

scarf analytics