nuqs

@nuqs.dev

370 Followers 1 Following

Type-safe search params state manager for React frameworks. Like useState, but stored in the URL query string. Made by @francoisbest.com & contributors 🔗 https://nuqs.dev

npm install, {pnpm,yarn,bun} add nuqs@latest
?n=u&q=s - Type-Safe Search Params State Manager for React npm i pnpm add yarn add bun add nuqs@latest
?n=u&q=s - Type-Safe Search Params State Manager for React npm i pnpm add yarn add bun add nuqs@latest
?n=u&q=s, Type-safe search params state manager for React 10,000 stars on GitHub: 47ng/nuqs
A Christmas-themed AI-generated artwork of the nuqs logo. The ? is a candy cane, the n is wrapped in lights, the = is a pair of logs covered in snow, the u is filled with baubles, the & is a wreath, the q has a santa hat and a glowing star atop, the = is two candy canes, and the s is another wreath. A lit up Christmas tree and snowflakes in the background
?n=u&q=s - Type-Safe Search Params State Manager for React npm i pnpm add yarn add bun add nuqs@latest
<download icon> 40M
?n=u&q=s - Type-Safe Search Params State Manager for React npm i pnpm add yarn add bun add nuqs@latest
?n=u&q=s Type-Safe Search Params State Manager for React npm i pnpm add yarn add bun add nuqs@latest
?n=u&q=s - Type-Safe Search Params State Manager for React npm i pnpm add yarn add bun add nuqs@latest
?n=u&q=s Type-Safe Search Params State Manager for React npm i pnpm add yarn add bun add nuqs@latest
install nuqs@latest using your favourite package manager
Homepage: nuqs.dev 🩷 Fund this package Weekly downloads: 1004771 Version: 2.7.2 License: MIT
npm i, {pnpm, yarn, bun} add nuqs@latest
nuqs stargazers count: 9001
npm i, {pnpm,yarn,bun} add nuqs@latest
import { useQueryState, parseAsNativeArrayOf, parseAsInteger } from 'nuqs' const [projectIds, setProjectIds] = useQueryState( 'project', parseAsNativeArrayOf(parseAsInteger) ) // ?project=123&project=456 → [123, 456] Demo: ?nativeArray=123&nativeArray=456&nativeArray=789 [123,456,789]
feat: multi-parsers #1134 PR by TkDodo MultiParsers allow **key repetition** in the URL. E.g.: with the built-in `parseAsNativeArrayOf`: ```ts const [state] = useQueryState('key', parseAsNativeArrayOf(parseAsInteger)) // url: /?key=1&key=2&key=3 // state: [1, 2, 3] ``` Creating custom multi-parsers allow reducing the array of query values into more complex objects: ```ts // /?kv=foo:bar&kv=baz:qux { foo: 'bar', baz: 'qux' } ```
nuqs • Send all URL updates to the server <NuqsAdapter defaultOptions={{ shallow: false }}> {children} </NuqsAdapter>
nuqs.dev Drop the 47ng. Just nuqs. It's cleaner.
{npm i, {pnpm,yarn,bun} add} nuqs@latest
install nuqs@latest
{npm i,{pnpm,yarn,bun} add} nuqs@latest
Do I need debounce? Debounce only makes sense for server-side data fetching (RSCs & loaders, when combined with shallow: false), to control when requests are made to the server. For example: it lets you avoid sending the first character on its own when typing in a search input, by waiting for the user to finish typing. The state returned by the hooks is always updated immediately: only the network requests sent to the server are debounced. If you are fetching client-side (eg: with TanStack Query), you’ll want to debounce the returned state instead (using a 3rd party useDebounce utility hook).
Dominik on stage at React Paris with a slide reading "🙏 Please try out betas & pre-releases"
export function RootLayout({ children }) { return ( // Always send updates to the server 👇 <NuqsAdapter defaultOptions={{ shallow: false }}> {children} </NuqsAdapter> ) }
install nuqs@beta with your favourite package manager
nuqs says “Hello, TanStack Router”, with icons of various projects: Vite, React, React Router, Next.js, Remix, TanStack (circled red) and Vitest. pnpm add nuqs@beta
47ng/nuqs has 8k stars on GitHub
{npm i, pnpm add, yarn add, bun add} nuqs@beta
{npm i, pnpm add, yarn add, bun add} nuqs@beta
▲/?n=u&q=s
Star emoji with 7k next to it, for the github.com/47ng/nuqs repository
import { isParserBijective, testParseThenSerialize, testSerializeThenParse } from 'nuqs/testing' it('is bijective', () => { // Passing tests return true expect(isParserBijective(parseAsInteger, '42', 42)).toBe(true) // Failing test throws an error expect(() => isParserBijective(parseAsInteger, '42', 47)).toThrowError() // You can also test either side separately: expect(testParseThenSerialize(parseAsInteger, '42')).toBe(true) expect(testSerializeThenParse(parseAsInteger, 42)).toBe(true) // Those will also throw an error if the test fails, // which makes it easier to isolate which side failed: expect(() => testParseThenSerialize(parseAsInteger, 'not a number')).toThrowError() expect(() => testSerializeThenParse(parseAsInteger, NaN)).toThrowError() })
import { parseAsIndex } from "nuqs"; export function usePageIndex() { const [pageIndex, setPageIndex] = useQueryState( "page" parseAsIndex.withDefault(0), }; // URL is 1-indexed: /?page=1 // state is 0-indexed: pageIndex === 0 }
6k stars for the github.com/47ng/nuqs repository.
import { parseAsFloat, type UrlKeys } from 'nuqs' const coordinates = { latitude: parseAsFloat.withDefault(0), longitude: parseAsFloat.withDefault(0), } const coordinatesUrlKeys: UrlKeys<typeof coordinates> = { // These keys are type-safe latitude: 'lat', longitude: 'lgn' } // Reuse the definitions everywhere useQueryStates(coordinates, { urlKeys: coordinatesUrlKeys }) createSerializer(coordinates, { urlKeys: coordinatesUrlKeys }) createLoader(coordinates, { urlKeys: coordinatesUrlKeys })
Try out nuqs@latest
pnpm add nuqs@latest