Build pages where reload doesn't erase what the user was doing

Overview

Every "open" / "selected" / "expanded" state writes to the URL via useUrlState. On mount, the component reads the URL and hydrates its initial state. A "Share this view" button copies the current URL to the clipboard. That's the whole pattern.

SMB operators live in two browser tabs and a half-dozen WhatsApp threads. They will reload your page, hit back, and send links to their bookkeeper at 2am. If "reload" wipes the four filters they spent forty seconds setting, they will not blame the browser — they will blame you, and rightly so. Persisting state through the URL is the bare minimum a serious app can do.

If reload erases it, the user loses trust. Every "open" / "selected" / "expanded" UI state belongs in the URL. Local state is for transient things — keystrokes mid-typing, hover affordances, drag previews. Everything else is a query param.

The mechanism is one hook (useUrlState) with a schema. The schema declares each param's type and parser. The hook reads from location.search on mount, writes back with history.replaceState on change (so the back button doesn't pile up history entries for filter toggles), and exposes a typed [state, setState] tuple. No router needed.

Skip this recipe if your page is a single-purpose form (sign-up, sign-in, settings) — there's nothing to share, nothing to restore. Those pages should not be URL-stateful.

What you'll build

Three states: fresh load with filters from URL, share button, restored after reload.

Required pieces

Everything this recipe pulls from @corelithzw/react.

@corelithzw/react exports used here: useUrlState, FilterChips, Button, useToast. Everything else is plain React.

What goes in the URL, what stays in state

Step-by-step build

The schema is a typed dictionary: each key maps to a type (string, number, boolean, string[]) and an optional default. useUrlState uses the schema both to parse on mount and to serialise on change — so an unknown query param just gets dropped, and a missing one falls back to the default.

The hook does a history.replaceState on every setState — not pushState. That's deliberate: each filter toggle would otherwise add a back-button entry, and pressing Back would walk the user through every keystroke. Use pushState only for genuine page transitions (open a record, leave a record).

The search input is the one place where local state matters — you don't want a URL write per keystroke. Keep a local query for typing, push it to the URL after 250ms of quiet. On Back/Forward, sync local back to URL so the input doesn't show stale text.

One button, one navigator.clipboard.writeText(location.href), one confirmation toast. Make sure the URL is canonical first — strip empty/default values so the link doesn't have ?q=&tier=&dir=asc noise. useUrlState already does this when you serialise, so the address bar matches the share link.

Final composition

The whole SuppliersList page: URL schema, debounced search, filter chips, selected row, share button.

Variations

Three forks.

useUrlState<State>(schema, {
  source: 'hash', // default is 'search'
});
// URL: /suppliers#tier=A&sel=acme

const saveView = async () => {
  const name = prompt('Name this view');
  if (!name) return;
  await fetch('/api/views', { method: 'POST',
    body: JSON.stringify({ name,
      path: window.location.pathname + window.location.search }) });
};

useUrlState<State>(schema, {
  source: 'sessionStorage',
  key: 'huchu:suppliers:draft',
});
// Survives reload, not shareable.

Accessibility

What this recipe takes care of for you.

• Reload restores focus. If the URL has sel=acme-metals, the matching row gets scrollIntoView + focus on mount — a keyboard user lands exactly where they were.
• Selected row exposes state. aria-selected={s.sel === r.id} on the row, so screen readers say "Acme Metals, selected" without you needing a separate label.
• Expanded sections are real disclosures. aria-expanded={openId === id} on the toggle button; assistive tech announces "billing, expanded" / "billing, collapsed".
• Share button confirms via live region. The success toast uses role="status" + aria-live="polite" so users hear "Link copied" without a visual cue.
• Back/Forward update state announce-ably. The URL sync triggers a re-render; if the filter chips change, their aria-pressed updates and screen readers pick it up.
• Filter and search labels are explicit. aria-label="Search suppliers" on the input; FilterChips groups carry a role="group" with the group name.
• Clipboard fallback works without HTTPS. If navigator.clipboard isn't available (insecure context on older Android), the recipe falls back to a hidden textarea + execCommand.

Related recipes

More shell + state patterns.