use-address-state


A lightweight React hook for managing state in URL search params. Built with useSyncExternalStore for optimal performance and tear-free reads.

Live Demo →

View on npm →

Why use-address-state?

- Tiny footprint – ~1KB minified, zero dependencies
- Selective re-rendering – Only components subscribed to changed keys re-render
- Shareable URLs – State persists across page refreshes and link sharing
- Full TypeScript support – Generic types for complete type safety
- Browser navigation – Seamless back/forward button support

Installation

``bash


npm

npm install use-address-state

yarn

yarn add use-address-state

pnpm

pnpm add use-address-state
`

Quick Start

`tsx
import { useAddressState } from "use-address-state";

function SearchPage() {
const [query, setQuery] = useAddressState("q");

return setQuery(e.target.value)} placeholder="Search..." />;
}
`

API Reference

$3

Syncs a single URL search param with React state.

#### Parameters

| Parameter | Type | Required | Description |
| -------------- | -------- | -------- | ------------------------------------------ |
| key | string | Yes | The URL search param key to sync with |
| initialValue | T | No | Default value when the param is not in URL |

#### Returns

[value, setValue] – A tuple similar to useState.

- value – Current value from URL (parsed from JSON) or initialValue
- setValue(newValue) – Updates the URL param. Pass null to remove it.

#### Examples

`tsx
// Basic string state
const [name, setName] = useAddressState("name");

// Typed state with default value
const [count, setCount] = useAddressState("count", 0);

// Remove param from URL
setCount(null);
`

Usage Patterns

$3

Components using the same key automatically share state without prop drilling:

`tsx
// search-bar.tsx
export function SearchBar() {
const [query, setQuery] = useAddressState("q");
return setQuery(e.target.value)} />;
}

// search-results.tsx
export function SearchResults() {
const [query] = useAddressState("q");
return

;
}
`

$3

Only components subscribed to a specific key re-render when that key changes:

`tsx
function CounterA() {
const [count, setCount] = useAddressState("a", 0);
// Only re-renders when 'a' changes
return setCount(count + 1)}>A: {count};
}

function CounterB() {
const [count, setCount] = useAddressState("b", 0);
// Only re-renders when 'b' changes
return setCount(count + 1)}>B: {count};
}
`

Requirements

- React 18.0.0 or higher
- Modern browser with URLSearchParams` support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Vinod Liyanage