nuqs

Manage type-safe URL query state in React applications with adapters.

1|Updated Jan 21, 2026
One-click install
npx skills add https://github.com/noklip-io/agent-skills --skill nuqs
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: nuqs
Source: https://github.com/noklip-io/agent-skills/tree/main/skills/nuqs
Command: npx skills add https://github.com/noklip-io/agent-skills --skill nuqs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill provides a type-safe approach to managing URL query parameters in React apps, enabling reliable, readable, and testable state synced with the browser URL.

Core Features & Use Cases

  • URL-based state management: Use hooks like useQueryState and useQueryStates to mirror UI state in the URL.
  • Adapter-first workflow: Works with Next.js, Remix, React Router, or plain React via dedicated adapters.
  • Server Components support: Supports server-side patterns with createSearchParamsCache for server access.

Quick Start

Wrap your app with the NuqsAdapter and start using useQueryState to bind URL params to UI state.

Frequently Asked Questions about nuqs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I manage URL query parameters as type-safe state in React?

You can manage URL query parameters as type-safe state in React using hooks like useQueryState and useQueryStates. These hooks mirror your UI state directly in the browser URL, ensuring reliable and readable synchronization.

Does URL query state work with Next.js, Remix, and React Router?

Yes, URL query state works with Next.js, Remix, React Router, and plain React through dedicated adapters. You must wrap your application with the appropriate NuqsAdapter to enable the URL state synchronization.

How do I access URL search params from React Server Components?

You can access URL search params from React Server Components using the createSearchParamsCache pattern. This server-side approach allows you to read and parse URL state securely on the server.

What is the best way to update multiple URL parameters at once in React?

The best way to update multiple URL parameters at once in React is by using the useQueryStates hook. This hook allows you to bind multiple URL params to your UI state and supports batch updates for efficient synchronization.

Why do I need an adapter to sync React state with the URL?

You need an adapter to sync React state with the URL because different frameworks like Next.js, Remix, and React Router handle routing differently. The adapter-first workflow provides the necessary integration layer for the URL state hooks to function.

How do I parse custom data types from URL search params in React?

To parse custom data types from URL search params in React, you use the built-in parsers provided by the library alongside useQueryState. These parsers ensure type-safe extraction and validation of query values from the URL.