nuqs
DocumentationPlaygroundRegistryBlog

Shadcn Registry

Use the shadcn CLI to install custom parsers, adapters and utilities from the community.

Type-safe linking for Next.js (using typedRoutes + nuqs)

npx shadcn@latest add https://nuqs.dev/r/next-typed-links.json
TypeScript
src/lib/typed-links.ts
import type { Route } from 'next'
import {
  createSerializer,
  type CreateSerializerOptions,
  type ParserMap
} from 'nuqs/server'

export function createTypedLink<Parsers extends ParserMap>(
  route: Route,
  parsers: Parsers,
  options: CreateSerializerOptions<Parsers> = {}
) {
  const serialize = createSerializer<Parsers, Route, Route>(parsers, options)
  return serialize.bind(null, route)
}

Usage

This utility connects your typedRoutes type-safe pathnames to a search params descriptor object, and gives you back a function you can call to generate a fully type-safe (pathname + search params) href for linking & routing:

src/app/map/search-params.ts
import { createTypedLink } from '@/src/lib/typed-links'
import { parseAsFloat, type UrlKeys } from 'nuqs/server'

const coordinates = {
  latitude: parseAsFloat.withDefault(0),
  longitude: parseAsFloat.withDefault(0)
}
// Optional remapping for shorter keys
const urlKeys: UrlKeys<typeof coordinates> = {
  latitude: 'lat',
  longitude: 'lng'
}

export const getMapLink = createTypedLink(
  '/map', // The values here are inferred from your app's routes
  coordinates,
  { urlKeys }
)

// Usage:
getMapLink({ latitude: 12.34, longitude: 56.78 })
// "/map?lat=12.34&lng=56.78"