nuqs: Type-Safe URL State Management for React Frameworks

nuqs: Type-Safe URL State Management for React Frameworks

Summary

nuqs is a powerful, type-safe state manager for React frameworks that stores component state directly in the URL query string. It offers a `useState`-like API, making it intuitive to manage URL parameters while ensuring type safety across various React environments. This library simplifies complex URL state synchronization, providing a robust solution for modern web applications.

Repository Info

Updated on October 12, 2025
View on GitHub

Tags

query-paramsreactsearch-paramsstate-managementtype-safeurl-stateTypeScriptFrontend Development

Click on any tag to explore related repositories

Introduction

nuqs is an innovative, type-safe state manager designed for React frameworks, allowing you to store and manage component state directly within the URL query string. Think of it as useState, but with the added benefit of persistence and shareability through the URL. This approach makes the URL the single source of truth for your application's state, enhancing user experience and SEO.

It supports a wide array of React environments, including Next.js (both app and pages routers), plain React (SPA), Remix, React Router, and TanStack Router, thanks to its flexible adapter system. Key features include built-in parsers for common data types, batching of state updates, server-side capabilities for accessing search parameters, and integration with React's useTransition for loading states.

Installation

Getting started with nuqs is straightforward. You can install it using your preferred package manager:

pnpm add nuqs

yarn add nuqs

npm install nuqs

After installation, you will need to wrap your React component tree with the appropriate adapter for your framework. For example, with Next.js (app router):

// src/app/layout.tsx
import { NuqsAdapter } from 'nuqs/adapters/next/app'
import { type ReactNode } from 'react'

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html>
      <body>
        <NuqsAdapter>{children}</NuqsAdapter>
      </body>
    </html>
  )
}

Examples

nuqs provides a familiar API, similar to React's useState. Here's a basic example demonstrating how to manage a name parameter in the URL:

'use client' // Only works in client components

import { useQueryState } from 'nuqs'

export default () => {
  const [name, setName] = useQueryState('name')
  return (
    <>
      <h1>Hello, {name || 'anonymous visitor'}!</h1>
      <input value={name || ''} onChange={e => setName(e.target.value)} />
      <button onClick={() => setName(null)}>Clear</button>
    </>
  )
}

For non-string state types, nuqs offers a variety of built-in parsers, such as parseAsInteger, parseAsBoolean, parseAsTimestamp, and parseAsJson, ensuring your URL state is always correctly typed and handled:

import {
  parseAsInteger,
  parseAsBoolean
} from 'nuqs'

useQueryState('count', parseAsInteger)
useQueryState('darkMode', parseAsBoolean)

Why Use nuqs?

  • Type Safety: nuqs enforces type safety for your URL parameters, significantly reducing common bugs and improving code reliability. You define the expected types, and the library handles the parsing and serialization.
  • URL as Source of Truth: By storing state in the URL, your application becomes more shareable, bookmarkable, and resilient to page refreshes. This is crucial for applications with filters, pagination, or complex views.
  • Framework Agnostic: With dedicated adapters, nuqs seamlessly integrates with popular React frameworks and routers, providing a consistent API regardless of your chosen stack.
  • Rich Features: Beyond basic state management, nuqs offers advanced features like custom parsers, batching of multiple query updates, server-side search parameter access, and SEO considerations for canonical URLs.
  • Developer Experience: The useState-like API makes nuqs incredibly intuitive for React developers, allowing for quick adoption and efficient development of URL-driven UIs.

Links