🔗 useUrlState

A powerful React hook for managing state synchronized with URL search parameters. Perfect for creating shareable URLs, maintaining filters across page refreshes, and building user-friendly web applications with deep linking support.

✨ Features

• 🎯 Type-safe - Full TypeScript support with generic types
• 🔄 Automatic URL sync - State changes are reflected in the URL instantly
• ⏱️ Debouncing - Prevent excessive URL updates during rapid state changes
• 🧭 Browser history - Full support for back/forward navigation
• 🏷️ Namespacing - Avoid conflicts when using multiple instances
• 🛡️ Validation - Built-in sanitization and validation hooks
• 📦 Custom serialization - Define custom codecs for complex data types
• 🪶 Lightweight - Zero dependencies (except React peer dependency)

📦 Installation

# Using npm
npm install use-url-state-reacthook

# Using yarn
yarn add use-url-state-reacthook

# Using pnpm
pnpm add use-url-state-reacthook

🚀 Quick Start

import { useUrlState } from "use-url-state-reacthook";

function SearchFilters() {
  const [filters, filtersApi] = useUrlState({
    search: "",
    category: "all",
    page: 1,
  });

  return (
    <div>
      <input
        value={filters.search}
        onChange={(e) => filtersApi.set("search", e.target.value)}
        placeholder="Search..."
      />

      <select
        value={filters.category}
        onChange={(e) => filtersApi.set("category", e.target.value)}
      >
        <option value="all">All Categories</option>
        <option value="tech">Technology</option>
        <option value="design">Design</option>
      </select>

      <div>Current page: {filters.page}</div>
      <button onClick={() => filtersApi.set("page", filters.page + 1)}>
        Next Page
      </button>
    </div>
  );
}

The URL will automatically update to something like: ?search=react&category=tech&page=2

📚 API Reference

useUrlState(defaults?, options?)

Returns a tuple [state, api] where:

• state: The current state object
• api: Object with methods to manipulate the state

Parameters

| Parameter | Type | Description | | ---------- | -------------------- | --------------------------------------- | | defaults | T \| (() => T) | Default values for the state (optional) | | options | UrlStateOptions<T> | Configuration options (optional) |

Options

| Option | Type | Default | Description | | ---------------- | ------------------------------------------ | ----------- | -------------------------------------------- | | codecs | Partial<{ [K in keyof T]: Codec<T[K]> }> | {} | Custom serialization for specific properties | | sanitize | (draft: Partial<T>) => Partial<T> | undefined | Validation/sanitization function | | onChange | (state: T, meta) => void | undefined | Callback fired on state changes | | history | 'replace' \| 'push' | 'replace' | Browser history behavior | | debounceMs | number | undefined | Debounce delay for URL updates | | syncOnPopState | boolean | true | Sync state on browser navigation | | namespace | string | undefined | Prefix for URL parameters |

API Methods

| Method | Signature | Description | | ---------- | ---------------------------------------- | ------------------------------ | | setState | (updater: T \| (prev: T) => T) => void | Replace entire state | | get | (key: keyof T) => T[key] | Get value of specific property | | set | (key: keyof T, value: T[key]) => void | Set specific property | | patch | (partial: Partial<T>) => void | Merge partial changes | | remove | (...keys: (keyof T)[]) => void | Remove properties | | clear | () => void | Clear all state |

🎯 Examples

Basic Usage

import { useUrlState } from "use-url-state-reacthook";

function App() {
  const [state, api] = useUrlState({ name: "", age: 0 });

  return (
    <div>
      <input
        value={state.name}
        onChange={(e) => api.set("name", e.target.value)}
      />
      <input
        type="number"
        value={state.age}
        onChange={(e) => api.set("age", parseInt(e.target.value) || 0)}
      />
      <button onClick={() => api.clear()}>Clear All</button>
    </div>
  );
}

With Custom Serialization

interface Filters {
  tags: string[];
  dateRange: { start: Date; end: Date };
  settings: { theme: string; lang: string };
}

const [filters, api] = useUrlState<Filters>(
  {
    tags: [],
    dateRange: { start: new Date(), end: new Date() },
    settings: { theme: "light", lang: "en" },
  },
  {
    codecs: {
      tags: {
        parse: (str) => str.split(",").filter(Boolean),
        format: (tags) => tags.join(","),
      },
      dateRange: {
        parse: (str) => {
          const [start, end] = str.split("|").map((d) => new Date(d));
          return { start, end };
        },
        format: (range) =>
          `${range.start.toISOString()}|${range.end.toISOString()}`,
      },
    },
  }
);

With Validation and Debouncing

const [userPrefs, api] = useUrlState(
  {
    theme: "light",
    fontSize: 16,
    language: "en",
  },
  {
    sanitize: (draft) => ({
      theme: ["light", "dark"].includes(draft.theme) ? draft.theme : "light",
      fontSize: Math.max(12, Math.min(24, draft.fontSize || 16)),
      language: ["en", "fr", "es"].includes(draft.language)
        ? draft.language
        : "en",
    }),
    debounceMs: 300, // Wait 300ms before updating URL
    onChange: (newState, { source }) => {
      console.log(`Preferences updated from ${source}:`, newState);
      // Save to analytics, localStorage, etc.
    },
  }
);

Multiple Hook Instances with Namespacing

function Dashboard() {
  // User filters (prefixed with 'user_')
  const [userFilters, userApi] = useUrlState(
    {
      role: "all",
      department: "all",
    },
    { namespace: "user" }
  );

  // Product filters (prefixed with 'product_')
  const [productFilters, productApi] = useUrlState(
    {
      category: "all",
      inStock: true,
    },
    { namespace: "product" }
  );

  // URL: ?user_role=admin&user_department=engineering&product_category=electronics&product_inStock=true
}

Complex State Management

interface AppState {
  filters: {
    search: string;
    category: string[];
    priceRange: [number, number];
  };
  view: "grid" | "list";
  sort: { field: string; direction: "asc" | "desc" };
}

const [appState, api] = useUrlState<AppState>({
  filters: {
    search: "",
    category: [],
    priceRange: [0, 1000],
  },
  view: "grid",
  sort: { field: "name", direction: "asc" },
});

// Update nested properties
api.patch({
  filters: {
    ...appState.filters,
    search: "new search term",
  },
});

// Toggle sort direction
api.set("sort", {
  ...appState.sort,
  direction: appState.sort.direction === "asc" ? "desc" : "asc",
});

🔧 Advanced Configuration

History Management

// Replace current URL (default)
const [state, api] = useUrlState(defaults, { history: "replace" });

// Create new history entries (enables back/forward navigation between state changes)
const [state, api] = useUrlState(defaults, { history: "push" });

Disabling Browser Navigation Sync

// Don't sync state when user uses back/forward buttons
const [state, api] = useUrlState(defaults, { syncOnPopState: false });

Performance Optimization

// Debounce URL updates for better performance with rapid changes
const [searchState, api] = useUrlState(
  { query: "" },
  {
    debounceMs: 300, // Wait 300ms before updating URL
  }
);

// Perfect for search inputs that update frequently
<input
  value={searchState.query}
  onChange={(e) => api.set("query", e.target.value)}
/>;

📝 TypeScript Support

The hook is fully typed and provides excellent TypeScript integration:

interface UserFilters {
  name: string;
  roles: ("admin" | "user" | "guest")[];
  isActive: boolean;
  metadata?: { lastLogin: Date };
}

// Full type safety
const [filters, api] = useUrlState<UserFilters>({
  name: "",
  roles: [],
  isActive: true,
});

// TypeScript knows the exact shape
api.set("name", "john"); // ✅ Valid
api.set("roles", ["admin", "user"]); // ✅ Valid
api.set("invalidProp", "value"); // ❌ TypeScript error

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by the need for better URL state management in React applications
• Built with TypeScript for maximum developer experience
• Designed to be simple yet powerful for real-world use cases

Happy coding! 🚀 If you find this hook useful, please consider giving it a ⭐ on GitHub!