state-in-url

# state-in-url > A React hook library for storing typed, JSON-serializable state in URL query parameters. ~2 KB, zero runtime deps. Supports the Next.js App Router (14/15/16), React Router 6/7, Remix 2, and plain React. MIT licensed. Last updated: 2026-07-31. Canonical: <https://state-in-url.dev/llms.txt>. ## For AI coding agents — preferred path This package ships task-focused SKILL.md files via [@tanstack/intent](https://tanstack.com/intent/latest/docs/overview). If your agent supports Intent, that is the right surface to load instead of this file: ```bash # in the user's project, once npx @tanstack/intent@latest install # list skills available for installed libraries npx @tanstack/intent@latest list # load a specific skill into the current context npx @tanstack/intent@latest load state-in-url#feature-state-hook ``` Available skills (under `node_modules/state-in-url/skills/`): | Skill | Type | When to load | |---|---|---| | `feature-state-hook` | core | Defining state and wrapping `useUrlState` in a feature-scoped custom hook | | `input-handling` | core | Text inputs / sliders / fast-changing controls | | `nextjs-ssr` | framework | Next.js App Router: `searchParams` forwarding, Proxy for layouts | | `react-router-remix-setup` | framework | React Router v6/v7 or Remix v2 setup | | `form-library-integration` | composition | Pairing with `react-hook-form` (or formik) | | `shared-state-no-url` | core | `useSharedState` — cross-component state without URL sync | The rest of this file is a condensed reference for agents that cannot load Intent skills. ## Package info - npm: https://www.npmjs.com/package/state-in-url - repo: https://github.com/asmyshlyaev177/state-in-url - website: https://state-in-url.dev - full README: https://raw.githubusercontent.com/asmyshlyaev177/state-in-url/refs/heads/master/README.md ## Supported frameworks | Framework | Versions | Import path | |---|---|---| | Next.js (App Router only) | 14 / 15 / 16 | `state-in-url/next` | | React Router | v7 | `state-in-url/react-router` | | React Router | v6 | `state-in-url/react-router6` | | Remix | v2 | `state-in-url/remix` | | Framework-agnostic | — | `state-in-url` (`useSharedState`), `state-in-url/encodeState` | Pages Router is **not** supported. ## Install ```bash npm install state-in-url ``` In `tsconfig.json`, ensure `"moduleResolution": "Bundler"` (or `"Node16"` / `"NodeNext"`). ## Core rules — read first 1. **Type, never interface.** The hook's generic constraint `JSONCompatible<T>` rejects `interface`. Always declare a `type` AND annotate the const: `const FOO_STATE: FooState = { ... }`. 2. **Default-state object must be a module-scoped `const`.** Never built from props, hook returns, or destructuring inside a component. Sharing is keyed by object identity. 3. **One feature → one shared default-state const → one custom hook.** Components import the hook, never `useUrlState` directly with their own defaults object. 4. **No secrets in URL.** Entity IDs (`jobId`, `memberId`) are fine; tokens, API keys, PII are not. 5. **JSON-serializable only.** Functions, BigInt, Symbol, Map, Set, class instances will not round-trip. Dates are supported. 6. **URL size**: keep total query-string under ~12 KB to stay safe across CDNs (Vercel header limit is 14 KB). ## API: `useUrlState` ```typescript const { urlState, setState, setUrl, reset } = useUrlState(DEFAULT_STATE, options?); ``` - `urlState` — current state, typed identically to `DEFAULT_STATE`. - `setState(value)` — updates internal state synchronously; **does not touch URL**. - `setUrl(value, opts?)` — updates state + URL. URL write is throttled (next tick). - `reset(opts?)` — sets state and URL back to `DEFAULT_STATE`. Setter call signatures (both `setState` and `setUrl`): ```typescript setUrl({ field: 'newValue' }); // partial patch setUrl(curr => ({ ...curr, field: 'newValue' })); // functional with current setUrl((curr, initial) => initial); / […gekürzt]