using-nuqs_skill

Overview

This skill shows how to manage React state in URL query parameters using nuqs for shareable filters, search inputs, toggles, and deep-linkable dialogs. It provides practical patterns for Suspense boundaries, parsing common types, clearing params, and controlling dialogs via the URL for reproducible links. The goal is predictable, bookmarkable UX with minimal wiring.

How this skill works

The skill replaces local useState with useQueryState from nuqs to keep state synced to the URL. It uses nuqs parsers (string, boolean, arrays) to convert between URL values and typed state and relies on a Suspense boundary because useSearchParams is used internally. Dialog visibility and other UI state become deep-linkable by storing identifiers or flags in query params and clearing them by setting the state to null.

When to use it

• You want filters, searches, or toggles to be shareable via URL
• You need deep-linkable dialogs or modals that open from a link
• You want URL-driven state that survives reloads and can be bookmarked
• You prefer zero-server routing changes and minimal client state plumbing
• You need typed parsing for arrays, booleans, and strings in query params

Best practices

• Wrap client components that use nuqs in a public Suspense wrapper so consumers don’t need to manage Suspense themselves
• Use nuqs parsers (parseAsString, parseAsBoolean, parseAsArrayOf) with .withDefault() when sensible to provide predictable values
• Clear URL params by setting the corresponding query state to null; with .withDefault() this removes the param but returns the default value in code
• Keep query param names short and stable to avoid breaking saved links
• Control dialogs via an id or flag param and reset it on close to keep URL and UI in sync

Example use cases

• SearchInput component that syncs the q param for shareable searches and preserves value across reloads
• Filter bar where tags, toggles, and search are synced to tags, archived, and q params for bookmarkable filter sets
• Delete confirmation dialog opened by setting delete=<id> in the URL, allowing deep links to specific confirmations
• Row actions that set a query param to open a modal for editing or viewing an item
• Clear filters button that sets multiple query states to null to reset the URL