@tanstack/svelte-table 9.0.0-beta.38 → 9.0.0-beta.42

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,236 +0,0 @@
1
- ---
2
- name: svelte/client-to-server
3
- description: >
4
- Convert a client-side Svelte table to server-side (manual) modes. Toggle `manualPagination`,
5
- `manualSorting`, `manualFiltering`, `manualGrouping`, `manualExpanding` for whatever the server
6
- owns, drop the matching row-model factory slots from `tableFeatures` and any `features` you no
7
- longer need, supply `rowCount` for the pager, then drive the request from `table.atoms.pagination`
8
- / `table.atoms.sorting` / etc. (or external atoms you own) using rune-aware getters
9
- (`get data()`, `get rowCount()`) so the table re-syncs in `$effect.pre`. Svelte 5+ only.
10
- type: lifecycle
11
- library: tanstack-table
12
- framework: svelte
13
- library_version: '9.0.0-alpha.48'
14
- requires:
15
- - state-management
16
- - pagination
17
- - filtering
18
- - sorting
19
- - svelte/table-state
20
- sources:
21
- - TanStack/table:examples/svelte/basic-external-atoms/
22
- - TanStack/table:examples/svelte/basic-external-state/
23
- - TanStack/table:examples/svelte/with-tanstack-query/
24
- - TanStack/table:docs/framework/svelte/guide/table-state.md
25
- ---
26
-
27
- # Client → Server (Svelte)
28
-
29
- You have a working client-side table. The dataset is too big to ship to the browser, or it
30
- lives behind an API. You want sorting / filtering / pagination to run on the server while the
31
- table still feels the same in the UI.
32
-
33
- ## Mental model
34
-
35
- Each "manual mode" flag tells the table: **don't run this stage of the pipeline; trust the data
36
- you receive.** You can mix modes freely — manual pagination + client-side sorting on the
37
- already-paged window is perfectly valid for medium datasets.
38
-
39
- | Flag | Meaning | What you must provide |
40
- | ------------------ | -------------------------------------------- | ----------------------------------------------------------- |
41
- | `manualPagination` | Server owns slicing; do not paginate locally | `rowCount` (or `pageCount`) |
42
- | `manualSorting` | Server owns ordering | Sort the server query by `sorting` state |
43
- | `manualFiltering` | Server owns row filtering | Filter the server query by `columnFilters` / `globalFilter` |
44
- | `manualGrouping` | Server returns already-grouped rows | Pre-shaped data |
45
- | `manualExpanding` | Server resolves sub-rows | Server-provided sub-row tree |
46
-
47
- When a stage is manual, you can drop its row-model factory slot from `tableFeatures`. `manualPagination: true` does not need `paginatedRowModel: createPaginatedRowModel()` in the features object.
48
-
49
- ## Step 1 — Identify what's moving server-side
50
-
51
- For a typical "search and paginate against a database" screen:
52
-
53
- - Pagination → server
54
- - Filtering (column filter inputs + a global search box) → server
55
- - Sorting → server (usually, since a partial page can't be sorted client-side meaningfully)
56
- - Selection / visibility / column ordering → still client
57
-
58
- So the table keeps `rowSelectionFeature` etc., drops `columnFilteringFeature` /
59
- `rowPaginationFeature` / `rowSortingFeature` _row models_ but keeps the _features_ so the
60
- state slices and UI APIs still exist.
61
-
62
- > Subtle point: keep the **feature** even if you drop the row model. The feature is what gives
63
- > you `column.getCanSort()`, `table.setPageIndex()`, `column.setFilterValue()` — all the
64
- > control-surface APIs. Dropping it kills the UI.
65
-
66
- ## Step 2 — Own the relevant state with external atoms
67
-
68
- External atoms make state portable: the data layer (a fetch / query / store) can read the
69
- same atoms the table writes to. Use `@tanstack/svelte-store`:
70
-
71
- ```ts
72
- import { createAtom, useSelector } from '@tanstack/svelte-store'
73
- import type {
74
- ColumnFiltersState,
75
- PaginationState,
76
- SortingState,
77
- } from '@tanstack/svelte-table'
78
-
79
- const paginationAtom = createAtom<PaginationState>({
80
- pageIndex: 0,
81
- pageSize: 10,
82
- })
83
- const sortingAtom = createAtom<SortingState>([])
84
- const filtersAtom = createAtom<ColumnFiltersState>([])
85
-
86
- // For Svelte markup that should react to changes:
87
- const pagination = useSelector(paginationAtom)
88
- const sorting = useSelector(sortingAtom)
89
- const filters = useSelector(filtersAtom)
90
- ```
91
-
92
- ## Step 3 — Configure the table
93
-
94
- ```svelte
95
- <script lang="ts">
96
- import {
97
- columnFilteringFeature,
98
- createTable,
99
- rowPaginationFeature,
100
- rowSortingFeature,
101
- tableFeatures,
102
- } from '@tanstack/svelte-table'
103
-
104
- const features = tableFeatures({
105
- columnFilteringFeature,
106
- rowPaginationFeature,
107
- rowSortingFeature,
108
- })
109
-
110
- // No row-model factories for these — server owns them.
111
- const table = createTable({
112
- features,
113
- columns,
114
- get data() {
115
- return query.data?.rows ?? []
116
- },
117
- get rowCount() {
118
- return query.data?.rowCount
119
- },
120
- atoms: {
121
- pagination: paginationAtom,
122
- sorting: sortingAtom,
123
- columnFilters: filtersAtom,
124
- },
125
- manualPagination: true,
126
- manualSorting: true,
127
- manualFiltering: true,
128
- })
129
- </script>
130
- ```
131
-
132
- `rowCount` is what makes `table.getPageCount()` / `table.getCanNextPage()` correct under
133
- manual pagination. Without it the pager has no idea how many pages exist.
134
-
135
- ## Step 4 — Drive the fetch from those atoms
136
-
137
- Wire whatever data layer you use (TanStack Query, a raw `fetch`, SvelteKit `load`, etc.) to
138
- read the atoms. With TanStack Query:
139
-
140
- ```ts
141
- import { createQuery, keepPreviousData } from '@tanstack/svelte-query'
142
-
143
- const dataQuery = createQuery<{ rows: Array<Person>; rowCount: number }>(
144
- () => ({
145
- queryKey: ['people', pagination.current, sorting.current, filters.current],
146
- queryFn: () =>
147
- fetch('/api/people', {
148
- method: 'POST',
149
- body: JSON.stringify({
150
- pageIndex: pagination.current.pageIndex,
151
- pageSize: pagination.current.pageSize,
152
- sorting: sorting.current,
153
- filters: filters.current,
154
- }),
155
- }).then((r) => r.json()),
156
- placeholderData: keepPreviousData,
157
- }),
158
- )
159
- ```
160
-
161
- `placeholderData: keepPreviousData` is what kills the "rows blank for one tick on every
162
- page change" flash.
163
-
164
- ## Step 5 — Reset behavior
165
-
166
- When the user changes a filter, you usually want to jump back to page 0. The table does this
167
- automatically when client-side filtering owns the data, but with manual mode the data layer
168
- controls it. Simplest fix: explicitly reset.
169
-
170
- ```ts
171
- $effect(() => {
172
- // re-runs whenever filters.current identity changes
173
- filters.current
174
- table.setPageIndex(0)
175
- })
176
- ```
177
-
178
- Or wrap your filter `onChange` handlers to also call `table.setPageIndex(0)`.
179
-
180
- ## Step 6 — A note on global filtering
181
-
182
- If you also support `globalFilterFeature`, debounce the input. `column.setFilterValue` and
183
- `table.setGlobalFilter` fire per keystroke; without debouncing you fire one request per typed
184
- character. See the `compose-with-tanstack-pacer` skill for the pattern.
185
-
186
- ## Hybrid example — manual pagination only
187
-
188
- Sometimes you only paginate server-side and let the page-sized window sort/filter on the
189
- client.
190
-
191
- ```ts
192
- const table = createTable({
193
- features: tableFeatures({
194
- columnFilteringFeature,
195
- rowPaginationFeature,
196
- rowSortingFeature,
197
- filteredRowModel: createFilteredRowModel(), // client filters the page
198
- sortedRowModel: createSortedRowModel(), // client sorts the page
199
- filterFns,
200
- sortFns,
201
- }),
202
- columns,
203
- get data() {
204
- return query.data?.rows ?? []
205
- },
206
- get rowCount() {
207
- return query.data?.rowCount
208
- },
209
- atoms: { pagination: paginationAtom },
210
- manualPagination: true,
211
- })
212
- ```
213
-
214
- Only the manual flag for the stage you're moving server-side.
215
-
216
- ## Common failure modes
217
-
218
- - **Forgot `rowCount`.** `table.getPageCount()` returns `-1`, the pager looks broken.
219
- - **Dropped the feature, not just the row model.** Lost `column.getCanSort()` and friends.
220
- Keep the feature when you still need its UI APIs; only drop the row-model factory.
221
- - **Both `state.pagination` and `atoms.pagination`.** Atoms silently win; the `on*Change`
222
- callback never fires.
223
- - **Re-creating atoms inside reactive blocks.** Atoms must be stable across renders. Declare
224
- them at module / component-init scope, not inside `$derived` or `$effect`.
225
- - **Forgetting to reset page on filter change.** Stay on page 12 of a now-2-page result set.
226
- - **Plain `data: query.data?.rows`.** No getter, no reactivity. Use `get data()`.
227
- - **Reimplementing pagination math.** `table.setPageIndex / nextPage / previousPage /
228
- firstPage / lastPage / setPageSize / getCanNextPage / getCanPreviousPage / getPageCount`
229
- already exist and respect manual mode.
230
-
231
- ## Related skills
232
-
233
- - `tanstack-table/svelte/compose-with-tanstack-query` — the same flow with a Query data layer.
234
- - `tanstack-table/svelte/compose-with-tanstack-pacer` — debouncing filter inputs.
235
- - `tanstack-table/svelte/compose-with-tanstack-store` — atom interop and per-slice subscription.
236
- - `tanstack-table/core/pagination` / `filtering` / `sorting` — feature deep dives.
@@ -1,294 +0,0 @@
1
- ---
2
- name: svelte/compose-with-tanstack-form
3
- description: >
4
- Editable cells in `@tanstack/svelte-table` powered by `@tanstack/svelte-form`. The table is the
5
- layout primitive; the form owns the state. Use `createFormHook` to register reusable field
6
- components (`TextField`, `NumberField`, `SelectField`), then in each column's `cell` renderer
7
- return `renderComponent(MyFieldCell, { form, rowIndex, fieldName })` and inside that cell call
8
- `form.Field` (or an `AppField`) with `name="data[${rowIndex}].${fieldName}"`. Drive the table's
9
- `data` from `form.state.values.data`. Svelte 5+ only.
10
- type: composition
11
- library: tanstack-table
12
- framework: svelte
13
- library_version: '9.0.0-alpha.48'
14
- requires:
15
- - row-selection
16
- - column-definitions
17
- sources:
18
- - TanStack/table:examples/svelte/with-tanstack-form/
19
- - TanStack/table:docs/framework/svelte/svelte-table.md
20
- ---
21
-
22
- # Compose with TanStack Form (Svelte)
23
-
24
- Editable tables are a classic source of state-management chaos. With v9 + TanStack Form, the
25
- division of labor is crisp:
26
-
27
- - **Form** owns the editable values (per-row, per-field).
28
- - **Table** owns the layout (columns, filtering, pagination of the same form data).
29
- - **Cells** are just field renderers — they read and write through Form's field APIs.
30
-
31
- ## Install
32
-
33
- ```bash
34
- pnpm add @tanstack/svelte-form @tanstack/svelte-table
35
- ```
36
-
37
- ## Set up a field-component-rich Form hook
38
-
39
- Define a `createAppForm` once with the reusable field components. This is the form-side
40
- equivalent of `createTableHook`.
41
-
42
- ```ts
43
- // hooks/form.ts
44
- import { createFormHook, createFormHookContexts } from '@tanstack/svelte-form'
45
- import TextField from '../components/TextField.svelte'
46
- import NumberField from '../components/NumberField.svelte'
47
- import SelectField from '../components/SelectField.svelte'
48
- import SubmitButton from '../components/SubmitButton.svelte'
49
- import FormStateIndicator from '../components/FormStateIndicator.svelte'
50
-
51
- export const { fieldContext, formContext } = createFormHookContexts()
52
-
53
- export const { useAppForm: createAppForm } = createFormHook({
54
- fieldComponents: { TextField, NumberField, SelectField },
55
- formComponents: { SubmitButton, FormStateIndicator },
56
- fieldContext,
57
- formContext,
58
- })
59
- ```
60
-
61
- ## Reusable field cell components
62
-
63
- Each cell type is a small Svelte component that knows which row + field it edits and uses
64
- `form.Field`. The shape is the same across types — `TextFieldCell`, `NumberFieldCell`,
65
- `SelectFieldCell`.
66
-
67
- ```svelte
68
- <!-- TextFieldCell.svelte -->
69
- <script lang="ts">
70
- type Props = {
71
- form: ReturnType<typeof createAppForm>
72
- rowIndex: number
73
- fieldName: string
74
- }
75
- let { form, rowIndex, fieldName }: Props = $props()
76
- </script>
77
-
78
- <form.Field name={`data[${rowIndex}].${fieldName}`}>
79
- {#snippet children(field)}
80
- <input
81
- type="text"
82
- value={field.state.value}
83
- oninput={(e) => field.handleChange((e.target as HTMLInputElement).value)}
84
- onblur={field.handleBlur}
85
- />
86
- {#if field.state.meta.errors?.length}
87
- <small class="error">{field.state.meta.errors.join(', ')}</small>
88
- {/if}
89
- {/snippet}
90
- </form.Field>
91
- ```
92
-
93
- ## Wire the table to form state
94
-
95
- ```svelte
96
- <script lang="ts">
97
- import {
98
- columnFilteringFeature,
99
- createColumnHelper,
100
- createFilteredRowModel,
101
- createPaginatedRowModel,
102
- createTable,
103
- filterFns,
104
- FlexRender,
105
- renderComponent,
106
- rowPaginationFeature,
107
- tableFeatures,
108
- } from '@tanstack/svelte-table'
109
- import { z } from 'zod'
110
- import { createAppForm } from './hooks/form'
111
- import TextFieldCell from './TextFieldCell.svelte'
112
- import NumberFieldCell from './NumberFieldCell.svelte'
113
- import SelectFieldCell from './SelectFieldCell.svelte'
114
- import { makeData, type Person } from './makeData'
115
-
116
- const features = tableFeatures({
117
- rowPaginationFeature,
118
- columnFilteringFeature,
119
- filteredRowModel: createFilteredRowModel(),
120
- paginatedRowModel: createPaginatedRowModel(),
121
- filterFns,
122
- })
123
-
124
- const columnHelper = createColumnHelper<typeof features, Person>()
125
-
126
- const personSchema = z.object({
127
- firstName: z.string().min(1),
128
- lastName: z.string().min(1),
129
- age: z.number().min(0).max(150),
130
- visits: z.number().min(0),
131
- progress: z.number().min(0).max(100),
132
- status: z.enum(['relationship', 'complicated', 'single']),
133
- })
134
-
135
- const formSchema = z.object({ data: z.array(personSchema) })
136
- type FormData = z.infer<typeof formSchema>
137
-
138
- const form = createAppForm(() => ({
139
- defaultValues: { data: makeData(1_000) } as FormData,
140
- validators: { onChange: formSchema },
141
- onSubmit: ({ value }) => alert(`Saved ${value.data.length} rows`),
142
- }))
143
-
144
- const columns = columnHelper.columns([
145
- columnHelper.accessor('firstName', {
146
- header: 'First Name',
147
- cell: ({ row }) =>
148
- renderComponent(TextFieldCell, {
149
- form,
150
- rowIndex: row.index,
151
- fieldName: 'firstName',
152
- }),
153
- }),
154
- columnHelper.accessor('age', {
155
- header: 'Age',
156
- cell: ({ row }) =>
157
- renderComponent(NumberFieldCell, {
158
- form,
159
- rowIndex: row.index,
160
- fieldName: 'age',
161
- }),
162
- }),
163
- columnHelper.accessor('status', {
164
- header: 'Status',
165
- cell: ({ row }) =>
166
- renderComponent(SelectFieldCell, {
167
- form,
168
- rowIndex: row.index,
169
- }),
170
- }),
171
- // ...
172
- ])
173
-
174
- const table = createTable({
175
- features,
176
- columns,
177
- get data() {
178
- // The form is the source of truth.
179
- return form.state.values.data
180
- },
181
- })
182
- </script>
183
-
184
- <form
185
- onsubmit={(e) => {
186
- e.preventDefault()
187
- void form.handleSubmit()
188
- }}
189
- >
190
- <form.AppForm>
191
- {#snippet children()}
192
- <form.FormStateIndicator />
193
- <form.SubmitButton label="Save" />
194
- {/snippet}
195
- </form.AppForm>
196
-
197
- <button
198
- type="button"
199
- onclick={() =>
200
- form.pushFieldValue('data', {
201
- firstName: '',
202
- lastName: '',
203
- age: 0,
204
- visits: 0,
205
- progress: 0,
206
- status: 'single',
207
- })}>Add Row</button
208
- >
209
-
210
- <table>
211
- <thead>
212
- {#each table.getHeaderGroups() as headerGroup (headerGroup.id)}
213
- <tr>
214
- {#each headerGroup.headers as header (header.id)}
215
- <th><FlexRender {header} /></th>
216
- {/each}
217
- </tr>
218
- {/each}
219
- </thead>
220
- <tbody>
221
- {#each table.getRowModel().rows as row (row.id)}
222
- <tr>
223
- {#each row.getAllCells() as cell (cell.id)}
224
- <td><FlexRender {cell} /></td>
225
- {/each}
226
- </tr>
227
- {/each}
228
- </tbody>
229
- </table>
230
- </form>
231
- ```
232
-
233
- ## Why `row.index` and not `row.id`?
234
-
235
- Form indexes its arrays positionally. `row.index` is the position inside the **current** row
236
- model (after filter + sort + paging). If you want a positional address into `form.state.values.data`,
237
- you usually want the **original** index — pass `row.original` somewhere that exposes it, or
238
- store an `id` field and look it up.
239
-
240
- For the common case where the table renders the array in its natural order (no sort, no
241
- filter that reorders), `row.index` matches the form-array position.
242
-
243
- ## Add Row / Remove Row
244
-
245
- Use the form's array helpers; the table re-renders because its `data` getter points at
246
- `form.state.values.data`.
247
-
248
- ```ts
249
- form.pushFieldValue('data', newPerson)
250
- form.removeFieldValue('data', rowIndex)
251
- form.replaceFieldValue('data', rowIndex, updatedPerson)
252
- ```
253
-
254
- ## Pairing with selection
255
-
256
- Add `rowSelectionFeature` to enable row checkboxes, then a "delete selected" button can use
257
- `table.getSelectedRowModel()` to collect rows and `form.removeFieldValue` to remove them.
258
-
259
- ```ts
260
- const selectedRows = table.getSelectedRowModel().rows
261
- const indexesDesc = selectedRows.map((r) => r.index).sort((a, b) => b - a)
262
- for (const i of indexesDesc) {
263
- form.removeFieldValue('data', i)
264
- }
265
- table.resetRowSelection()
266
- ```
267
-
268
- Remove in descending order so earlier removals don't shift later indexes.
269
-
270
- ## Pairing with virtualization
271
-
272
- You can virtualize the rows even with editable cells — but be aware that **virtualized rows
273
- unmount when scrolled out of view**, taking their inline form fields with them. If a cell has
274
- unsaved local-only state, you'll lose it. Use Form fields (which live on the form's state)
275
- and you're fine — the field state survives the unmount.
276
-
277
- ## Common failure modes
278
-
279
- - **`renderComponent` from React docs.** Use the Svelte adapter's `renderComponent` from
280
- `@tanstack/svelte-table`. The signature is the same shape but the runtime is different.
281
- - **`form` not reactive in cells.** Pass `form` as a prop; don't reach for it via context
282
- unless you set up `formContext`.
283
- - **Wrong field name.** `data[${row.index}].firstName` — string template, not a plain join.
284
- - **Reordering / filtering breaks `row.index`.** As above. Either keep a stable id and resolve
285
- back to the form-array index, or accept that `row.index` only addresses the visible window.
286
- - **Editing inside virtualized rows without form state.** Field values lost on scroll.
287
- - **Reimplementing form state with `$state` per cell.** Defeats the whole point — Form already
288
- owns this state and runs validation.
289
-
290
- ## Related skills
291
-
292
- - `tanstack-table/core/row-selection` — checkbox column patterns.
293
- - `tanstack-table/core/column-definitions` — accessor / display columns.
294
- - `tanstack-table/svelte/table-state` — `getRowModel()` and reactivity.
@@ -1,176 +0,0 @@
1
- ---
2
- name: svelte/compose-with-tanstack-pacer
3
- description: >
4
- Use `@tanstack/svelte-pacer` to debounce / throttle high-frequency writes that drive a
5
- `@tanstack/svelte-table` v9 instance — column filter inputs and column resize state are the
6
- two hot paths. Import `createDebouncer` (or `createThrottler`) from
7
- `@tanstack/svelte-pacer/debouncer`, wrap the call site that hits `column.setFilterValue`,
8
- `table.setGlobalFilter`, or commits a resize, and call `.maybeExecute(value)` on each event.
9
- Svelte 5+ only — pacer instances live at component-init scope.
10
- type: composition
11
- library: tanstack-table
12
- framework: svelte
13
- library_version: '9.0.0-alpha.48'
14
- requires:
15
- - filtering
16
- - column-layout
17
- sources:
18
- - TanStack/table:examples/svelte/with-tanstack-form/
19
- - TanStack/table:docs/framework/svelte/guide/table-state.md
20
- ---
21
-
22
- # Compose with TanStack Pacer (Svelte)
23
-
24
- Two places in a v9 table take state writes at event-loop rate: **filter inputs** (one
25
- keystroke = one `setFilterValue`) and **column resizing** (one pointermove = one
26
- `columnSizing` write). Without rate-limiting they either flood the network (server-side
27
- filtering) or burn CPU on tens of thousands of re-renders per drag.
28
-
29
- `@tanstack/svelte-pacer` gives you `createDebouncer`, `createThrottler`, and friends. Wrap
30
- the call site and you're done.
31
-
32
- ## Install
33
-
34
- ```bash
35
- pnpm add @tanstack/svelte-pacer
36
- ```
37
-
38
- ## Debounce a column filter input
39
-
40
- Client-side debouncing reduces re-render churn. Server-side debouncing also kills request
41
- storms.
42
-
43
- ```svelte
44
- <script lang="ts">
45
- import { createDebouncer } from '@tanstack/svelte-pacer/debouncer'
46
- import type { Column } from '@tanstack/svelte-table'
47
-
48
- type Props = { column: Column<typeof features, Person> }
49
- let { column }: Props = $props()
50
-
51
- let localValue = $state((column.getFilterValue() as string) ?? '')
52
-
53
- const debouncedSetFilter = createDebouncer(
54
- (value: string) => column.setFilterValue(value),
55
- { wait: 200 },
56
- )
57
-
58
- function onInput(e: Event) {
59
- const value = (e.target as HTMLInputElement).value
60
- localValue = value
61
- debouncedSetFilter.maybeExecute(value)
62
- }
63
- </script>
64
-
65
- <input type="text" value={localValue} oninput={onInput} placeholder="Search…" />
66
- ```
67
-
68
- Why the `localValue`? So the input stays snappy (controlled by `$state`) while the table only
69
- sees the debounced commit.
70
-
71
- ## Debounce a global filter
72
-
73
- Same shape, calling `table.setGlobalFilter`:
74
-
75
- ```svelte
76
- <script lang="ts">
77
- import { createDebouncer } from '@tanstack/svelte-pacer/debouncer'
78
-
79
- let search = $state('')
80
- const debouncedSetGlobalFilter = createDebouncer(
81
- (value: string) => table.setGlobalFilter(value),
82
- { wait: 250 },
83
- )
84
- </script>
85
-
86
- <input
87
- type="text"
88
- value={search}
89
- oninput={(e) => {
90
- search = (e.target as HTMLInputElement).value
91
- debouncedSetGlobalFilter.maybeExecute(search)
92
- }}
93
- />
94
- ```
95
-
96
- ## Throttle column resizing
97
-
98
- `columnResizingFeature` (which requires `columnSizingFeature` to also be registered in `tableFeatures`) writes to `columnSizing` continuously. v9 supports `columnResizeMode:
99
- 'onChange' | 'onEnd'` — the default is `'onChange'` (commit per-frame). For very heavy tables,
100
- either:
101
-
102
- 1. Set `columnResizeMode: 'onEnd'` so the commit only happens at pointerup.
103
- 2. Or, keep `'onChange'` for the visual handle but throttle the side effects you fire off it.
104
-
105
- Throttle a side effect:
106
-
107
- ```ts
108
- import { createThrottler } from '@tanstack/svelte-pacer/throttler'
109
-
110
- const throttledSaveSizing = createThrottler(
111
- (sizing: ColumnSizingState) => persistColumnSizingToStorage(sizing),
112
- { wait: 100 },
113
- )
114
-
115
- $effect(() => {
116
- const sizing = table.atoms.columnSizing.get()
117
- throttledSaveSizing.maybeExecute(sizing)
118
- })
119
- ```
120
-
121
- ## Patterns to avoid
122
-
123
- ### Don't debounce inside a `$effect`
124
-
125
- ```ts
126
- // WRONG — new debouncer instance every effect re-run
127
- $effect(() => {
128
- const d = createDebouncer((v) => column.setFilterValue(v), { wait: 200 })
129
- d.maybeExecute(value)
130
- })
131
- ```
132
-
133
- Pacer instances must be stable. Declare them once at component init scope.
134
-
135
- ### Don't debounce things that should be immediate
136
-
137
- Selection toggles, page changes, sort clicks — these are user-driven discrete events. Don't
138
- debounce them. The user expects instant feedback.
139
-
140
- ### Don't double-commit
141
-
142
- ```ts
143
- // WRONG — local state syncs immediately AND the debounced commit fires
144
- oninput={(e) => {
145
- column.setFilterValue(e.currentTarget.value)
146
- debouncedSetFilter.maybeExecute(e.currentTarget.value)
147
- }}
148
- ```
149
-
150
- Pick one. If you want a snappy input, store the input value in local `$state` and only call
151
- the debounced commit.
152
-
153
- ## Coordinating with TanStack Query
154
-
155
- If your filter triggers a server query, debouncing the filter handler is necessary but not
156
- sufficient — `placeholderData: keepPreviousData` is what keeps the UI from flashing. See the
157
- `compose-with-tanstack-query` skill.
158
-
159
- ## Common failure modes
160
-
161
- - **Recreating pacer instances inside `$effect` / `$derived`.** Each re-run produces a fresh
162
- debouncer; nothing is ever delayed.
163
- - **Hand-rolled `setTimeout` debounce.** Loses leading-edge / trailing-edge guarantees; harder
164
- to cancel on unmount. Use pacer.
165
- - **Debouncing a value that drives layout.** Causes user-visible lag where there shouldn't
166
- be. Keep the input controlled by local state and only debounce the table-write call.
167
- - **Forgetting to call `.maybeExecute`.** Constructing a debouncer doesn't enqueue anything;
168
- you have to call `.maybeExecute(value)` per event.
169
- - **Reimplementing pacer with `$effect` timers.** Don't.
170
-
171
- ## Related skills
172
-
173
- - `tanstack-table/core/filtering` — column / global filter mechanics.
174
- - `tanstack-table/core/column-layout` — column resizing modes (`onChange` vs `onEnd`).
175
- - `tanstack-table/svelte/compose-with-tanstack-query` — pairing pacer with server queries.
176
- - `tanstack-table/svelte/production-readiness` — where pacer fits in the perf checklist.