JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 24392
  • Score
    100M100P100Q166036F
  • License ISC

Library to store state in browser URL, includes hook for NextJS, hook for pure React, and low level helpers.

Package Exports

  • state-in-url

Readme

state-in-url

Library logo

Seamlessly store complex React state object in URL query parameters without losing types. Works with Next.js/React.js applications.

Don't hesitate to open issue if you found a bug

DEMO

Add a ⭐️ to support the project!

For hire

npm Tests Commitizen friendly npm bundle size (minified + gzip)

Features

  • Seamless state synchronization with URL query parameters.
  • Preserves shape and types of data
  • Full TypeScript support for enhanced developer experience.
  • Automatic serialization and deserialization of complex objects.
  • Separate hooks for Next.js (useUrlState) and React.js (useUrlEncode) usage.
  • Efficient updates with minimal re-renders.
  • Lightweight, no dependencies.

Table of content

installation

# npm
npm install --save state-in-url
# yarn
yarn add state-in-url
# pnpm
pnpm add state-in-url

Run locally

Clone this repo, run npm install and

npm run dev

Go to localhost:3000

useUrlState hook for Next.js

useUrlState is a custom React hook for Next.js applications that make communication between client components easy. It allows you to store and retrieve state from the URL search parameters, providing a way to persist state across page reloads and share application state via URLs.

Usage examples

Basic

'use client'
import { useUrlState } from 'state-in-url';

// State shape should be stored in a constant, don't pass an object directly
const countState = { count: 0 };

function MyComponent() {
  const { state, updateState, updateUrl } = useUrlState(countState);

  // won't let you to accidently mutate state directly, requires TS
  // state.count = 2 // <- error

  return (
    <div>
      <p>Count: {state.count}</p>

      <button onClick={() => updateUrl({ count: state.count + 1 }), { replace: true }}>
        Increment (Update URL)
      </button>

      <button onClick={() => updateState({ count: state.count + 1 })}>
        Increment (Local Only)
      </button>
      <button onClick={() => updateUrl(state)}>
        Sync changes to url
      </button>
    </div>
  )
}

With complex state shape

'use client'
import { useUrlState } from 'state-in-url';

interface UserSettings {
  theme: 'light' | 'dark';
  fontSize: number;
  notifications: boolean;
}

const defaultSettings: UserSettings {
  theme: 'light',
  fontSize: 16,
  notifications: true,
}

function SettingsComponent() {
  // `state` will infer from UserSettings type!
  const { state, updateUrl } = useUrlState(defaultSettings);

  const toggleTheme = () => {
    updateUrl(current => ({
      ...current,
      theme: current.theme === 'light' ? 'dark' : 'light',
    }));
  };

  return (
    <div>
      <h2>User Settings</h2>
      <p>Theme: {state.theme}</p>
      <p>Font Size: {state.fontSize}px</p>
      <button onClick={toggleTheme}>Toggle Theme</button>
      {/* Other UI elements to update other settings */}
    </div>
  );
}
...

// Other component
function Component() {
  const { state } = useUrlState(defaultSettings);

  return (
    <div>
      <p>Notifications is {state.notifications ? 'On' : 'Off'}</p>
    </div>
  )
}
'use client'
import { useUrlState } from 'state-in-url';

const someObj = {};

function SettingsComponent() {
  const { state, updateUrl, updateState } = useUrlState<object>(someObj);
}

useUrlEncode hook for React.js

useUrlEncode is a custom React hook that provides utility functions for encoding and decoding state object to and from URL search parameters. This hook doesn't depend on Nextjs, and will works with any React application.

Accepts optional defaultState argument.

import { useUrlEncode } from 'state-in-url';

const Component = () => {
  const { parse, stringify } = useUrlEncode();

  const str = stringify({ age: 36 }); // age=∓36
  const obj = parse(str); // { age: 36 }

  const currentParams = parse(window.location.search);
  // OR
  // const obj = parse(new URLSearchParams(window.location.search))

  const updateSearch = () => {
    const currentParams = new URLSearchParams(window.location.search);
    const newState = { query: 'react hooks', page: 2 };
    const updatedParamsString = stringify(newState, currentParams);
    console.log(updatedParamsString);
    // Output: existing params + query=react%20hooks&page=2
  };
}

encodeState and decodeState helpers

encodeState let you encode some object with optional defaults, and optional existing queryString

 export const form = { name: '' };
...
 encodeState({ name: 'test' }, form, 'someExistingParam=123');

decodeState let you decode queryString with optional defaults

 export const form = { name: '' };
...
 decodeState('name=Alex', form);

encode and decode helpers

There low level helpers to stringify and parse query string params. Useful for other frameworks or pure JS.

import { encode, decode } from 'state-in-url';

const state = { obj: [1, 2, 3], obj2: true }

// to params
const params = new URLSearchParams();
Object.entries(state).forEach(([key, value]) => {
  params.set(key, encode(value));
});
const str = params.toString();

// from params
const obj = Object.fromEntries(
  [...params.entries()].map(([key, value]) => [
    key,
    decode(value),
  ]),
)

Gothas

  1. Can pass only serializable values, Function, BigInt or Symbol won't work, probably things like ArrayBuffer neither.

Contact & Support

Changelog

License

This project is licensed under the MIT license.

Inspiration

this article

NextJS useSearchParams