Get Started
A walk through @k8ordo/state with a product list whose filters live in the URL: define one state, then read and update it in a component.
On this page
Install
npm install @k8ordo/state zodIt runs with:
- React 19.3 or later
- TypeScript 7 or later, when you write TypeScript
The guide for AI agents ships at node_modules/@k8ordo/state/docs/GUIDE.md. Point your AGENTS.md or the like at that path.
In the browser, the URL is rewritten through the Navigation API. There is no polyfill and no fallback.
Note
The examples on this page use zod, and zod/mini works the same. See the zod/mini section of Places to choose between them.
Defining the state
src/state.tsimport { definePageState } from '@k8ordo/state';
import * as z from 'zod';
export const listState = definePageState('product-list', {
The state’s name. Pick one nothing else in the app uses
url: z.object({
inStock: z.stringbool().default(false),
page: z.coerce.number().int().min(1).default(1),
}),
});A shared link should open the same list, so the filters go in the URL. State kept in the URL is described with a schema in the url slot of definePageState.
A URL parameter can be missing, so every field gets a .default(). A URL carries only strings: read the number with z.coerce.number() and the boolean with z.stringbool().
Write the definition in a module without 'use client', and import it from Server Components and Client Components alike. Exported from a 'use client' file, it reaches a Server Component as a client reference, and href cannot be called on it.
Reading and updating in a component
src/components/filters.tsx'use client';
import { useAppState } from '@k8ordo/state';
import { listState } from '../state';
export function Filters() {
const [{ inStock, page }, update] = useAppState(listState);
return (
<div>
<label>
<input
checked={inStock}
onChange={(event) => {
update({ inStock: event.target.checked, page: 1 });
Rewrites the current history entry
}}
type="checkbox"
/>
In stock only
</label>
<button
onClick={() => {
update({ page: page + 1 }, { history: 'push' });
Adds a new history entry
}}
type="button"
>
Next page
</button>
</div>
);
}Hand the definition to useAppState in a Client Component. It returns the current values and update, which changes them.
A value passed to update() shows in the next render, and the URL is written after that. How writes are batched and awaited is covered in Updates.
By default update() rewrites the current history entry. Paging passes { history: 'push' }, so the browser’s back button returns to the previous page.
Filter demo
A definePageState that rewrites this page’s URL for real.
- Desk lampIn stock
- Wooden chairSold out
- Query
no query (all defaults)
Try it
- Check “In stock only”. The query becomes
?inStock=true, and only the products in stock are listed. - Press “Next page”.
page=2is added to the query. Then press the browser’s back button, and the list returns to page 1. - Uncheck the box.
inStockdisappears from the query:falseis its default, and defaults are not written to the URL.