Open History to see the last commit
1---
2id: localStorageCollectionOptions
3title: localStorageCollectionOptions
4---
5
6## Call Signature
7
8```ts
9function localStorageCollectionOptions<T, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, LocalStorageCollectionUtils> & object;
10```
11
12Defined in: [packages/db/src/local-storage.ts:318](https://github.com/TanStack/db/blob/main/packages/db/src/local-storage.ts#L318)
13
14Creates localStorage collection options for use with a standard Collection
15
16This function creates a collection that persists data to localStorage/sessionStorage
17and synchronizes changes across browser tabs using storage events.
18
19**Fallback Behavior:**
20
21When localStorage is not available (e.g., in server-side rendering environments),
22this function automatically falls back to an in-memory storage implementation.
23This prevents errors during module initialization and allows the collection to
24work in any environment, though data will not persist across page reloads or
25be shared across tabs when using the in-memory fallback.
26
27**Using with Manual Transactions:**
28
29For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`
30to persist changes made during `tx.mutate()`. This is necessary because local-storage collections
31don't participate in the standard mutation handler flow for manual transactions.
32
33### Type Parameters
34
35#### T
36
37`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\>
38
39#### TKey
40
41`TKey` *extends* `string` \| `number` = `string` \| `number`
42
43### Parameters
44
45#### config
46
47[`LocalStorageCollectionConfig`](../interfaces/LocalStorageCollectionConfig.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `T`, `TKey`\> & `object`
48
49Configuration options for the localStorage collection
50
51### Returns
52
53[`CollectionConfig`](../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, [`LocalStorageCollectionUtils`](../interfaces/LocalStorageCollectionUtils.md)\> & `object`
54
55Collection options with utilities including clearStorage, getStorageSize, and acceptMutations
56
57### Examples
58
59```ts
60// Basic localStorage collection
61const collection = createCollection(
62 localStorageCollectionOptions({
63 storageKey: 'todos',
64 getKey: (item) => item.id,
65 })
66)
67```
68
69```ts
70// localStorage collection with custom storage
71const collection = createCollection(
72 localStorageCollectionOptions({
73 storageKey: 'todos',
74 storage: window.sessionStorage, // Use sessionStorage instead
75 getKey: (item) => item.id,
76 })
77)
78```
79
80```ts
81// localStorage collection with mutation handlers
82const collection = createCollection(
83 localStorageCollectionOptions({
84 storageKey: 'todos',
85 getKey: (item) => item.id,
86 onInsert: async ({ transaction }) => {
87 console.log('Item inserted:', transaction.mutations[0].modified)
88 },
89 })
90)
91```
92
93```ts
94// Using with manual transactions
95const localSettings = createCollection(
96 localStorageCollectionOptions({
97 storageKey: 'user-settings',
98 getKey: (item) => item.id,
99 })
100)
101
102const tx = createTransaction({
103 mutationFn: async ({ transaction }) => {
104 // Use settings data in API call
105 const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)
106 await api.updateUserProfile({ settings: settingsMutations[0]?.modified })
107
108 // Persist local-storage mutations after API success
109 localSettings.utils.acceptMutations(transaction)
110 }
111})
112
113tx.mutate(() => {
114 localSettings.insert({ id: 'theme', value: 'dark' })
115 apiCollection.insert({ id: 2, data: 'profile data' })
116})
117
118await tx.commit()
119```
120
121## Call Signature
122
123```ts
124function localStorageCollectionOptions<T, TKey>(config): CollectionConfig<T, TKey, never, LocalStorageCollectionUtils> & object;
125```
126
127Defined in: [packages/db/src/local-storage.ts:338](https://github.com/TanStack/db/blob/main/packages/db/src/local-storage.ts#L338)
128
129Creates localStorage collection options for use with a standard Collection
130
131This function creates a collection that persists data to localStorage/sessionStorage
132and synchronizes changes across browser tabs using storage events.
133
134**Fallback Behavior:**
135
136When localStorage is not available (e.g., in server-side rendering environments),
137this function automatically falls back to an in-memory storage implementation.
138This prevents errors during module initialization and allows the collection to
139work in any environment, though data will not persist across page reloads or
140be shared across tabs when using the in-memory fallback.
141
142**Using with Manual Transactions:**
143
144For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`
145to persist changes made during `tx.mutate()`. This is necessary because local-storage collections
146don't participate in the standard mutation handler flow for manual transactions.
147
148### Type Parameters
149
150#### T
151
152`T` *extends* `object`
153
154#### TKey
155
156`TKey` *extends* `string` \| `number` = `string` \| `number`
157
158### Parameters
159
160#### config
161
162[`LocalStorageCollectionConfig`](../interfaces/LocalStorageCollectionConfig.md)\<`T`, `never`, `TKey`\> & `object`
163
164Configuration options for the localStorage collection
165
166### Returns
167
168[`CollectionConfig`](../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, [`LocalStorageCollectionUtils`](../interfaces/LocalStorageCollectionUtils.md)\> & `object`
169
170Collection options with utilities including clearStorage, getStorageSize, and acceptMutations
171
172### Examples
173
174```ts
175// Basic localStorage collection
176const collection = createCollection(
177 localStorageCollectionOptions({
178 storageKey: 'todos',
179 getKey: (item) => item.id,
180 })
181)
182```
183
184```ts
185// localStorage collection with custom storage
186const collection = createCollection(
187 localStorageCollectionOptions({
188 storageKey: 'todos',
189 storage: window.sessionStorage, // Use sessionStorage instead
190 getKey: (item) => item.id,
191 })
192)
193```
194
195```ts
196// localStorage collection with mutation handlers
197const collection = createCollection(
198 localStorageCollectionOptions({
199 storageKey: 'todos',
200 getKey: (item) => item.id,
201 onInsert: async ({ transaction }) => {
202 console.log('Item inserted:', transaction.mutations[0].modified)
203 },
204 })
205)
206```
207
208```ts
209// Using with manual transactions
210const localSettings = createCollection(
211 localStorageCollectionOptions({
212 storageKey: 'user-settings',
213 getKey: (item) => item.id,
214 })
215)
216
217const tx = createTransaction({
218 mutationFn: async ({ transaction }) => {
219 // Use settings data in API call
220 const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)
221 await api.updateUserProfile({ settings: settingsMutations[0]?.modified })
222
223 // Persist local-storage mutations after API success
224 localSettings.utils.acceptMutations(transaction)
225 }
226})
227
228tx.mutate(() => {
229 localSettings.insert({ id: 'theme', value: 'dark' })
230 apiCollection.insert({ id: 2, data: 'profile data' })
231})
232
233await tx.commit()
234```