# nuqs: Type-Safe URL State Management for React Frameworks
This repository profile is provided by osrepos.com, an open source repository discovery platform.
Source: osrepos.com
Repository profile: https://osrepos.com/repo/47ng-nuqs
Generated for open source discovery and AI-assisted research.
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.
GitHub: https://github.com/47ng/nuqs
OSRepos URL: https://osrepos.com/repo/47ng-nuqs
## 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.
## Topics
- query-params
- react
- search-params
- state-management
- type-safe
- url-state
- TypeScript
- Frontend Development
## Repository Information
Last analyzed by OSRepos: Sun Oct 12 2025 18:16:18 GMT+0100 (Western European Summer Time)
Detail views: 3
GitHub clicks: 11
## Safety Notice
OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.
## Content
## 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:
shell
pnpm add nuqs
shell
yarn add nuqs
shell
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):
tsx
// src/app/layout.tsx
import { NuqsAdapter } from 'nuqs/adapters/next/app'
import { type ReactNode } from 'react'
export default function RootLayout({ children }: { children: ReactNode }) {
return (
{children}
)
}
## 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:
tsx
'use client' // Only works in client components
import { useQueryState } from 'nuqs'
export default () => {
const [name, setName] = useQueryState('name')
return (
<>
Hello, {name || 'anonymous visitor'}!
setName(e.target.value)} />
)
}
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:
ts
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
* **GitHub Repository**: [https://github.com/47ng/nuqs](https://github.com/47ng/nuqs){:target="_blank"}
* **Official Documentation**: [https://nuqs.dev](https://nuqs.dev){:target="_blank"}
* **NPM Package**: [https://www.npmjs.com/package/nuqs](https://www.npmjs.com/package/nuqs){:target="_blank"}