What problem does it solve?
Keep multiple, related React components in sync using shared UI state that also survives reloads and can be shared via the URL, without adding Context providers or manually wiring props everywhere.
Core Features & Use Cases
- Module-scoped shared defaults: Define a static default-state const once and pass the same object identity into
useUrlState so components automatically share URL-synced state.
- Typed URL state patterns: Model feature state as JSON-serializable TypeScript types for drawer/modals, tab switching, multi-select toggles, paginators, filters, and selections.
- Clean reset/defaults semantics: Use defaults that represent “no selection” so reset removes query params, keeping URLs short and shareable.
Use case example: Store a job search UI with a selected tab and jobId in the URL so navigating between components (tabs, details panel, modal) stays consistent and deep-links correctly.
Quick Start
Define a single exported typed default object for your feature outside components, then call useUrlState(yourDefaultConst, { searchParams }) inside a custom hook that your UI components import and use.