state-in-url's 207-line llms.txt shows what thorough AI preparation looks like

# state-in-url

A React hook library for storing complex state objects in browser URLs with full TypeScript type preservation.

## What It Does

state-in-url synchronizes React state with URL query parameters, enabling:
- State sharing between unrelated components without prop drilling or context
- State persistence across page reloads via URL
- Shareable links that preserve application state
- Type-safe state management with full TypeScript inference

## Package Information

- **NPM:** https://www.npmjs.com/package/state-in-url
- **GitHub:** https://github.com/asmyshlyaev177/state-in-url
- **Website:** https://state-in-url.dev
- **Main Documentation:** https://raw.githubusercontent.com/asmyshlyaev177/state-in-url/refs/heads/master/README.md

## Supported Frameworks

| Framework | Versions | Documentation |
|-----------|----------|---------------|
| Next.js | v14-v15 | https://raw.githubusercontent.com/asmyshlyaev177/state-in-url/refs/heads/master/packages/urlstate/next/useUrlState/README.md |
| React Router | v7 | https://raw.githubusercontent.com/asmyshlyaev177/state-in-url/refs/heads/master/packages/urlstate/react-router/useUrlState/README.md |
| React Router | v6 | https://raw.githubusercontent.com/asmyshlyaev177/state-in-url/refs/heads/master/packages/urlstate/react-router6/useUrlState/README.md |
| Remix | v2 | https://raw.githubusercontent.com/asmyshlyaev177/state-in-url/refs/heads/master/packages/urlstate/remix/useUrlState/README.md |

## Installation

```bash
npm install state-in-url
```

## Import Paths by Framework

```typescript
// Next.js
import { useUrlState } from "state-in-url/next";

// React Router v7
import { useUrlState } from "state-in-url/react-router";

// React Router v6
import { useUrlState } from "state-in-url/react-router6";

// Remix
import { useUrlState } from "state-in-url/remix";
```

## Core API: useUrlState Hook

The primary hook for state management synchronized with URL query parameters.

**Returns:**
- `urlState`: Current state object with full type inference
- `setState`: Updates state immediately (batched URL sync)
- `setUrl`: Syncs state to URL immediately

## Basic Usage Example

```typescript
// 1. Define state type using 'type', not 'interface'
type FormState = {
  searchQuery: string;
  isFiltered: boolean;
  page: number;
};

// 2. Create initial state as static const (never from props/functions)
const initialState: FormState = {
  searchQuery: "",
  isFiltered: false,
  page: 1
};

function SearchComponent() {
  const { urlState, setState, setUrl } = useUrlState(initialState);

  return (
    <div>
      {/* Read state - fully typed */}
      <p>Current search: {urlState.searchQuery}</p>
      <p>Page: {urlState.page}</p>

      {/* Update state + URL immediately */}
      <button onClick={() => setUrl({ page: urlState.page + 1 })}>
        Next Page
      </button>

      {/* Update state instantly, sync URL on blur */}
      <input
        value={urlState.searchQuery}
        onChange={(e) => setState({ searchQuery: e.target.value })}
        onBlur={() => setUrl()}
      />

      {/* Reset to initial state */}
      <button onClick={() => setUrl((_, initial) => initial)}>
        Reset