@k8ordo/state

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

bash
npm install @k8ordo/state zod

It 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.

Information

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.ts
import { 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.

Playground

Filter demo

A definePageState that rewrites this page’s URL for real.

  • Desk lampIn stock
  • Wooden chairSold out
1 / 3
Query
no query (all defaults)

Try it

  1. Check “In stock only”. The query becomes ?inStock=true, and only the products in stock are listed.
  2. Press “Next page”. page=2 is added to the query. Then press the browser’s back button, and the list returns to page 1.
  3. Uncheck the box. inStock disappears from the query: false is its default, and defaults are not written to the URL.
k8ordo

React libraries that use Baseline features without holding back.