smart-query-state

A lightweight React hook for reading and managing URL query parameters in Next.js applications. Built on top of Next.js navigation primitives (useSearchParams, useRouter, usePathname).

Installation

npm install smart-query-state

Requires: Next.js 13+ (App Router) and React 18+

Usage

Basic — Reading a query param

'use client';

import { useQueryState } from 'smart-query-state';

export default function MyPage() {
  const { getQuery } = useQueryState();

  const name = getQuery('name'); // reads ?name=... from the URL

  return <p>Hello, {name}!</p>;
}

If your URL is /profile?name=shashi, then getQuery('name') returns "shashi".

API

useQueryState()

Returns an object with the following utilities:

| Method | Signature | Description | |---|---|---| | getQuery | (key: string) => string \| null | Reads the value of a URL query parameter by key. Returns null if not present. |

More methods like setQuery, removeQuery, and clearQuery are coming soon.

Requirements

• Next.js 13+ with the App Router
• Must be used inside a Client Component — add 'use client' at the top of any file that uses this hook

Notes

• This hook uses useSearchParams from next/navigation — make sure the component is wrapped in a <Suspense> boundary if required by your Next.js version.
• Do not use this hook in Server Components.

Roadmap

• [ ] getQuery(key) — ✅ Read a query param
• [ ] setQuery(key, value) — Update a query param
• [ ] removeQuery(key) — Remove a query param
• [ ] clearQuery() — Clear all query params

License

ISC