# Controlled state The engine never owns its state - **you do**. You pass `state` in and the engine calls your `onXxxChange` handlers with the next value. That one rule is what makes headless SvGrid click with Svelte 5 `$state`, and it's what lets state survive an unmount or be shared across two grids. ## The in/out contract ```ts let sorting = $state<{ id: string; desc: boolean }[]>([]) const table = $derived.by(() => createSvGrid({ _features: features, _rowModels: { coreRowModel: createCoreRowModel(), sortedRowModel: createSortedRowModel() }, data, columns, state: { sorting }, // ── in onSortingChange: (u) => // ── out (sorting = typeof u === 'function' ? u(sorting) : u), })) ``` The handler receives either the next value **or** an updater function - always handle both (`typeof u === 'function' ? u(prev) : u`). Because `sorting` is `$state` and `table` is `$derived`, changing it re-runs the pipeline. The same shape applies to every state channel: `onColumnFiltersChange`, `onPaginationChange`, `onGroupingChange`, `onExpandedChange`, `onRowSelectionChange`, `onColumnVisibilityChange`. ## `createGridState` - lift state out of the component Sometimes you want a piece of state to live **outside** the grid: so it survives an unmount, persists to storage, or is shared by two grids. `createGridState` returns a `[get, set]` tuple - a reactive store you own (`createSvGridState` is an alias). ```ts import { createGridState } from '@svgrid/grid/core' // [getter, setter] - the getter reads reactive $state, the setter takes a // value or an updater function. const [getSorting, setSorting] = createGridState([]) setSorting([{ id: 'stars', desc: true }]) // set a value setSorting((prev) => [...prev]) // or an updater console.log(getSorting()) // read it ``` Wire it into a grid via the `state` / `onXxxChange` channel: ```ts const table = $derived.by(() => createSvGrid({ get data() { return rows }, get columns() { return columns }, state: { sorting: getSorting() }, onSortingChange: setSorting, // the setter already handles updaters })) ``` ### Share one store across two grids Pass the **same** `[get, set]` pair to two engines and they stay in lockstep - sort in one, the other re-sorts, because both read the same reactive store. > Live demo: Two grids, one shared state - https://svgrid.com/demos/189-headless-shared-state/ ```ts const [getSorting, setSorting] = createGridState([]) const makeGrid = () => $derived.by(() => createSvGrid({ get data() { return rows }, get columns() { return columns }, state: { sorting: getSorting() }, onSortingChange: setSorting, })) const gridA = makeGrid() const gridB = makeGrid() // shares getSorting/setSorting -> stays in sync ``` ## `subscribeGrid` - react outside a component Inside a Svelte component, `$effect` is the natural way to react to grid changes. Outside one - a Svelte action, an analytics hook, an integration test - use `subscribeGrid` for a plain pub/sub interface (`subscribeSvGrid` is an alias). ```ts import { subscribeGrid } from '@svgrid/grid/core' const unsub = subscribeGrid(table, (event) => { if (event.type === 'sorting') analytics.track('grid_sort', event.value) if (event.type === 'rowSelection') syncSelectionToUrl(event.value) }) // later unsub() ``` ## You own the state Every slice you pass in `state` is yours: the engine reads it and reports changes through the matching `on*Change`, but never writes it. That is what lets the same value drive a URL, a saved view, or two grids at once. ```svelte

State: {JSON.stringify(sorting)}

    {#each rows as r (r.id)} {@const repo = r.original as Repo}
  1. {repo.name} - {repo.stars.toLocaleString()}
    2. {/each}
``` ## The updater can be a function An `on*Change` hands you either the next value or a function of the previous one, the way `setState` does. Handling only the value silently drops the toggle path, and a header click stops working. ```svelte {#each table.getHeaderGroups() as hg (hg.id)} {#each hg.headers as h (h.id)} {/each} {/each} {#each rows as r (r.id)} {@const repo = r.original as Repo} {/each}
{h.column.columnDef.header}
{repo.name}{repo.stars.toLocaleString()}

{updates} sort update(s)

``` ## See also - [Row models](https://svgrid.com/docs/help/headless/row-models/) - each channel feeds one pipeline step - [Build a table from scratch](https://svgrid.com/docs/help/headless/build-a-table/) - [Named views](https://svgrid.com/docs/help/state/named-views/) - the `` state save/restore equivalent --- SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/headless/controlled-state/ . All docs: https://svgrid.com/llms.txt