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