English | 한국어 | 简体中文

State in url

Why use state-in-url?

Store any user state in query parameters; imagine JSON in a browser URL. All of it with keeping types and structure of data, e.g. numbers will be decoded as numbers not strings, dates as dates, etc, objects and arrays supported. Dead simple, fast, and with static Typescript validation. Deep links, aka URL synchronization, made easy.

Contains useUrlState hook for Next.js and react-router, and helpers for anything else on JS. Since modern browsers support huge URLs and users don't care about query strings (it is a select all and copy/past workflow).

Time to use query string for state management, as it was originally intended. This library does all mundane stuff for you.

This library is a good alternative for NUQS.

Use cases

• Store unsaved user forms or page filters in URL
• Sycn URL with React state
• Just sync data between unrelated client components without touching URI
• Shareable URLs with application state (Deep linking, URL state synchronization)
• Easy state persistence across page reloads

Features

• 🧩 Simple: No providers, reducers, boilerplate or new concepts, API similar to React.useState
• 📘 Typescript validation/autocomplete: State is just an object, automatic static validation in IDE/tests according to Typescript definition
• ✨ Complex data: Nested objects, dates and arrays, works same as JSON, but in URL
• ☂ Default values: Giving you default values if parameter not in url
• ⌨ Organized: All possible values defined at start, protect you from getting non existing key
• flexible: Can use more than 1 state objects on the same page, just use different keys
• Fast: Minimal rerenders, around 1ms to encode and decode big object
• Server Side Rendering: Can use it in Server Components, Next.js 14 and 15 are supported
• Lightweight: Zero dependencies, library less than 2KB
• DX: Good developer experience, documentation, JSDoc comments, and examples
• Framework Flexibility: Hooks for Next.js and react-router, helpers to use it with other frameworks or pure JS
• Well tested: Unit tests and Playwright tests for Chrome/Firefox/Safari
• Permissive license: MIT

Table of content

• Installation
• useUrlState hook
• • Next.js
• • React-Router
• Other helpers
• • useUrlStateBase for other routers
• • useSharedState hook for React.js/Next.js
• • useUrlEncode for React.js
• • encodeState and decodeState for pure JS usage
• • Low-level encode and decode functions
• Best practices
• • Gotchas
• Other
• • Roadmap
• • Contributing
• • Contact & Support
• • Changelog
• • License
• • Inspiration

installation

1. Install package

1# npm
2npm install --save state-in-url
3# yarn
4yarn add state-in-url
5# pnpm
6pnpm add state-in-url

2. Edit tsconfig.json

In tsconfig.json in compilerOptions set "moduleResolution": "Bundler", or"moduleResolution": "Node16", or "moduleResolution": "NodeNext". Possibly need to set "module": "ES2022", or "module": "ESNext"

useUrlState

Main hook that takes initial state as parameter and returns state object, callback to update url, and callback to update only state. All components that use the same state object are automatically synchronized.

useUrlState hook for Next.js

Full API Docs

React-Router example

Usage examples

Basic

1. Define state shape with default values

1// userState.ts
2// Only parameters with value different from default will go to the url.
3export const userState: UserState = { name: '', age: 0 }
4
5// use `Type` not `Interface`!
6type UserState = { name: string, age: number }

2. Import it and use

1'use client'
2import { useUrlState } from 'state-in-url/next';
3
4import { userState } from './userState';
5
6function MyComponent() {
7  // can pass `replace` arg, it's control will `setUrl` will use `rounter.push` or `router.replace`, default replace=true
8  // can pass `searchParams` from server components
9  const { urlState, setUrl, setState, reset } = useUrlState(userState);
10
11  return (
12    <div>
13      // urlState.name will return default value from `userState` if url empty
14      <input value={urlState.name}
15        // same api as React.useState, e.g. setUrl(currVal => currVal + 1)
16        onChange={(ev) => setUrl({ name: ev.target.value }) }
17      />
18      <input value={urlState.age}
19        onChange={(ev) => setUrl({ age: +ev.target.value }) }
20      />
21
22      <input value={urlState.name}
23        onChange={(ev) => { setState(curr => ({ ...curr, name: ev.target.value })) }}
24        // Can update state immediately but sync change to url as needed
25        onBlur={() => setUrl()}
26      />
27
28      <button onClick={reset}>
29        Reset
30      </button>
31
32    </div>
33  )
34}

Custom hook to work with slice of state conveniently

1'use client';
2
3import React from 'react';
4import { useUrlState } from 'state-in-url/next';
5
6const form: Form = {
7  name: '',
8  age: undefined,
9  agree_to_terms: false,
10  tags: [],
11};
12
13type Form = {
14  name: string;
15  age?: number;
16  agree_to_terms: boolean;
17  tags: {id: string; value: {text: string; time: Date } }[];
18};
19
20export const useFormState = ({ searchParams }: { searchParams?: object }) => {
21  const { urlState, setUrl: setUrlBase, reset } = useUrlState(form, {
22    searchParams,
23  });
24
25  // first navigation will push new history entry
26  // all following will just replace that entry
27  // this way will have history with only 2 entries - ['/url', '/url?key=param']
28
29  const replace = React.useRef(false);
30  const setUrl = React.useCallback((
31      state: Parameters<typeof setUrlBase>[0],
32      opts?: Parameters<typeof setUrlBase>[1]
33    ) => {
34      setUrlBase(state, { replace: replace.current, ...opts });
35      replace.current = true;
36  }, [setUrlBase]);
37
38  return { urlState, setUrl, resetUrl: reset };
39};

With complex state shape

1export const form: Form = {
2  name: '',
3  age: undefined,
4  agree_to_terms: false,
5  tags: [],
6};
7
8type Form = {
9  name: string;
10  age?: number;
11  agree_to_terms: boolean;
12  tags: { id: string; value: { text: string; time: Date } }[];
13};

1'use client'
2import { useUrlState } from 'state-in-url/next';
3
4import { form } from './form';
5
6function TagsComponent() {
7  // `urlState` will infer from Form type!
8  const { urlState, setUrl } = useUrlState(form);
9
10  const onChangeTags = React.useCallback(
11    (tag: (typeof tags)[number]) => {
12      setUrl((curr) => ({
13        ...curr,
14        tags: curr.tags.find((t) => t.id === tag.id)
15          ? curr.tags.filter((t) => t.id !== tag.id)
16          : curr.tags.concat(tag),
17      }));
18    },
19    [setUrl],
20  );
21
22  return (
23    <div>
24      <Field text="Tags">
25        <div className="flex flex-wrap gap-2">
26          {tags.map((tag) => (
27            <Tag
28              active={!!urlState.tags.find((t) => t.id === tag.id)}
29              text={tag.value.text}
30              onClick={() => onChangeTags(tag)}
31              key={tag.id}
32            />
33          ))}
34        </div>
35      </Field>
36    </div>
37  );
38}
39
40const tags = [
41  {
42    id: '1',
43    value: { text: 'React.js', time: new Date('2024-07-17T04:53:17.000Z') },
44  },
45  {
46    id: '2',
47    value: { text: 'Next.js', time: new Date('2024-07-18T04:53:17.000Z') },
48  },
49  {
50    id: '3',
51    value: { text: 'TailwindCSS', time: new Date('2024-07-19T04:53:17.000Z') },
52  },
53];

Update state only and sync to URL manually

1
2const timer = React.useRef(0 as unknown as NodeJS.Timeout);
3React.useEffect(() => {
4  clearTimeout(timer.current);
5  timer.current = setTimeout(() => {
6    // will compare state by content not by reference and fire update only for new values
7    setUrl(urlState);
8  }, 500);
9
10  return () => {
11    clearTimeout(timer.current);
12  };
13}, [urlState, setUrl]);

1<input onBlur={() => updateUrl()} .../>

With server side rendering

1export default async function Home({ searchParams }: { searchParams: object }) {
2  return (
3    <Form searchParams={searchParams} />
4  )
5}
6
7// Form.tsx
8'use client'
9import React from 'react';
10import { useUrlState } from 'state-in-url/next';
11import { form } from './form';
12
13const Form = ({ searchParams }: { searchParams: object }) => {
14  const { urlState, setState, setUrl } = useUrlState(form, { searchParams });
15}

Using hook in layout component

1// add to appropriate `layout.tsc`
2export const runtime = 'edge';
3
4// middleware.ts
5import type { NextRequest } from 'next/server';
6import { NextResponse } from 'next/server';
7
8export function middleware(request: NextRequest) {
9  const url = request.url?.includes('_next') ? null : request.url;
10  const sp = url?.split?.('?')?.[1] || '';
11
12  const response = NextResponse.next();
13
14  if (url !== null) {
15    response.headers.set('searchParams', sp);
16  }
17
18  return response;
19}
20
21// Target layout component
22import { headers } from 'next/headers';
23import { decodeState } from 'state-in-url/encodeState';
24
25export default async function Layout({
26  children,
27}: {
28  children: React.ReactNode;
29}) {
30  const sp = headers().get('searchParams') || '';
31
32  return (
33    <div>
34      <Comp1 searchParams={decodeState(sp, stateShape)} />
35      {children}
36    </div>
37  );
38}
39
40

With arbitrary state shape (not recommended)

1'use client'
2import { useUrlState } from 'state-in-url/next';
3
4const someObj = {};
5
6function SettingsComponent() {
7  const { urlState, setUrl, setState } = useUrlState<object>(someObj);
8}

useUrlState hook for React-Router

API is same as for Next.js version, except can pass options from NavigateOptions type.

API Docs

Example

1export const form: Form = {
2  name: '',
3  age: undefined,
4  agree_to_terms: false,
5  tags: [],
6};
7
8type Form = {
9  name: string;
10  age?: number;
11  agree_to_terms: boolean;
12  tags: { id: string; value: { text: string; time: Date } }[];
13};
14

1import { useUrlState } from 'state-in-url/react-router';
2
3import { form } from './form';
4
5function TagsComponent() {
6  const { urlState, setUrl, setState } = useUrlState(form);
7
8  const onChangeTags = React.useCallback(
9    (tag: (typeof tags)[number]) => {
10      setUrl((curr) => ({
11        ...curr,
12        tags: curr.tags.find((t) => t.id === tag.id)
13          ? curr.tags.filter((t) => t.id !== tag.id)
14          : curr.tags.concat(tag),
15      }));
16    },
17    [setUrl],
18  );
19
20  return (
21    <div>
22      <Field text="Tags">
23        <div className="flex flex-wrap gap-2">
24          {tags.map((tag) => (
25            <Tag
26              active={!!urlState.tags.find((t) => t.id === tag.id)}
27              text={tag.value.text}
28              onClick={() => onChangeTags(tag)}
29              key={tag.id}
30            />
31          ))}
32        </div>
33      </Field>
34
35      <input value={urlState.name}
36        onChange={(ev) => { setState(curr => ({ ...curr, name: ev.target.value })) }}
37        // Can update state immediately but sync change to url as needed
38        onBlur={() => setUrl()}
39      />
40    </div>
41  );
42}
43
44const tags = [
45  {
46    id: '1',
47    value: { text: 'React.js', time: new Date('2024-07-17T04:53:17.000Z') },
48  },
49  {
50    id: '2',
51    value: { text: 'Next.js', time: new Date('2024-07-18T04:53:17.000Z') },
52  },
53  {
54    id: '3',
55    value: { text: 'TailwindCSS', time: new Date('2024-07-19T04:53:17.000Z') },
56  },
57];

Example code

Other hooks and helpers

useUrlStateBase hook for others routers

Hooks to create your own useUrlState hooks with other routers, e.g. react-router or tanstack router.

API Docs

useSharedState hook for React.js

Hook to share state between any React components, tested with Next.js and Vite.

1'use client'
2import { useSharedState } from 'state-in-url';
3
4export const someState = { name: '' };
5
6function SettingsComponent() {
7  const { state, setState } = useSharedState(someState);
8}

API Docs

useUrlEncode hook for React.js

API Docs

encodeState and decodeState helpers

API Docs

encode and decode helpers

API Docs

Best Practices

• Define your state shape as a constant
• Use TypeScript for enhanced type safety and autocomplete
• Avoid storing sensitive information in URL parameters (SSN, API keys etc)
• Use this extension for readable TS errors

Can create state hooks for slices of state, and reuse them across application. For example:

1type UserState = {
2  name: string;
3  age: number;
4  other: { id: string, value: number }[]
5};
6const userState = {
7  name: '',
8  age: 0,
9  other: [],
10};
11
12export const useUserState = () => {
13  const { urlState, setUrl, reset } = useUrlState(userState);
14
15  // other logic
16
17  // reset query params when navigating to other page
18  React.useEffect(() => {
19    return reset
20  }, [])
21
22  return { userState: urlState, setUserState: setUrl };;
23}
24

Gotchas

1. Can pass only serializable values, Function, BigInt or Symbol won't work, probably things like ArrayBuffer neither. Everything that can be serialized to JSON will work.
2. Vercel servers limit size of headers (query string and other stuff) to 14KB, so keep your URL state under ~5000 words. https://vercel.com/docs/errors/URL_TOO_LONG
3. Tested with next.js 14/15 with app router, no plans to support pages.

Other

Contribute and/or run locally

See Contributing doc

Roadmap

• hook for Next.js
• hook for react-router
• hook for remix
• hook for svelte
• hook for astro
• hook for store state in hash ?

Contact & Support

• Create a GitHub issue for bug reports, feature requests, or questions

Changelog

License

This project is licensed under the MIT license.

Inspiration

NUQS

Using URL to store state in Vue

Storing state in the URL

NextJS useSearchParams