History entry
Some state should come back with the back button but stay out of a shared link: an open row, an expanded panel. That state goes in entry.
On this page
The entry schema
orders-state.tsimport { definePageState } from '@k8ordo/state';
import * as z from 'zod';
export const ordersState = definePageState('orders', {
entry: z.object({
expanded: z.array(z.string()).default([]),
showNotes: z.boolean().default(false),
}),
});Pass definePageState an entry schema. The values never appear in the URL. They are stored in the state the Navigation API keeps for each history entry, under the definition’s key.
The values are stored typed, never turned into strings: a boolean is z.boolean() and a number is z.number(). A written value is validated by the schema again as the typed value it is. z.stringbool() or a type-changing transform lands on its default on every write.
The server has no history entry, so the server render and the hydration render show the defaults.
url and entry together
export const ordersState = definePageState('orders', {
url: z.object({
status: z.enum(['all', 'pending', 'shipped']).default('all'),
}),
entry: z.object({
expanded: z.array(z.string()).default([]),
}),
});
const [{ status, expanded }, update] = useAppState(ordersState);One definition can hold both url and entry. useAppState returns the two merged into one object.
Moving a field from url to entry changes nothing at the call sites. The spelling of a boolean does change: z.stringbool() in url becomes z.boolean() in entry.
Declaring the same field in both is a type error. At runtime, declaring status in both fails with "orders" declares in both url and entry: status.
Write routing
update({ status: 'pending' }, { history: 'push' });
One navigation.navigate()
update({ expanded: ['A-102'] });
updateCurrentEntry() on the current history entryOne update() can change both url and entry. Whether a url value changed decides how it is written.
- When a
urlvalue changes: onenavigation.navigate()carries the new URL and theentryvalues together. The page never renders with only one of the two changed. - When only
entryvalues change:navigation.updateCurrentEntry()rewrites the current history entry. No navigation happens, so it works under any router, and{ history: 'push' }creates no new history entry.
A write that changes the URL carries the current entry values over to the new history entry. Values other definitions keep on the history entry stay as they are.
Restore on browser actions
Both url and entry live on the browser’s history entry. The library keeps no record of its own. Back, forward and reload apply to both in the same way.
- Back and forward: the
urlandentryvalues of the history entry you land on come back together. - Reload: the page loads again on the same history entry, so both stay.
- Opening the URL in a new tab: the new tab receives only the URL.
urlhas the same values, andentrystarts from its defaults. - Following a link: the new history entry has no
entryvalues yet, so they start from the defaults. - Session restore: values an older schema wrote may come back. A value the schema rejects falls back to that field’s default alone.
url versus entry
A definePageState with the filter in url and the open orders in entry, rewriting this page’s URL and history entry for real.
- Shipped
- Pending
- Pending
- url
no query- entry
{ expanded: [] }
Try it
- Open “A-102”. The
entryvalue changes, and the URL’s query does not. - Switch the filter to “Pending”. The query becomes
?status=pending, and “A-102” stays open. - Open “A-103” too, then press the browser’s back button. The filter returns to “All”, and only “A-102” is open again.
- Reload the page. The filter and the open orders are still there.