URL State — nuqs

Documentation Index

Fetch the complete documentation index at: https://handbook.mhchq.ai/llms.txt

Use this file to discover all available pages before exploring further.

Tip: nuqs is a small, zero-dependency library (< 2 KB) that maps React state to URL search params with no boilerplate. It is the only way to store filter state in OpenInsure portals — useState for filter values is a bug.

​

Why the URL is the right place for filter state

1. Navigate away → filters reset — The user builds a filtered view, clicks into a record, hits back, and lands on the unfiltered default. They have to rebuild their query.
2. Refresh → filters reset — Same problem. Every refresh destroys work.
3. Can’t share a view — “Send me that filtered list” is not possible.

​

Setup — NuqsAdapter

import { NuqsAdapter } from 'nuqs/adapters/next/app';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider>
      <NuqsAdapter>{children}</NuqsAdapter>
    </QueryClientProvider>
  );
}

​

Usage — useQueryState

import { parseAsString, useQueryState } from 'nuqs';

// String filter with a default value
const [status, setStatus] = useQueryState('status', parseAsString.withDefault('all'));

// Multi-value filter (array)
import { parseAsArrayOf, parseAsString, useQueryState } from 'nuqs';
const [statuses, setStatuses] = useQueryState(
  'statuses',
  parseAsArrayOf(parseAsString).withDefault([])
);

​

Wiring to TanStack Query re-fetches

const [category, setCategory] = useQueryState('category', parseAsString.withDefault('all'));

const { data } = useQuery({
  queryKey: ['audit-events', category], // <-- nuqs value here
  queryFn: async () => {
    const params = new URLSearchParams();
    if (category !== 'all') params.set('resource_type', category);
    const res = await fetch(`/api/v1/audit?${params}`);
    return res.json();
  },
});

​

URL conventions

​

Carrier Portal

​

UW Workbench

​

Primitives reference

​

CSV export — filter-aware

function exportToCsv(events: AuditEvent[]) {
  const rows = events.map((e) =>
    [
      e.timestamp,
      e.actor.name,
      e.action,
      e.resource.type,
      e.resource.name,
      e.severity,
      e.status,
    ].join(',')
  );
  const blob = new Blob(
    [['timestamp,actor,action,resource_type,resource_name,severity,status', ...rows].join('\n')],
    { type: 'text/csv' }
  );
  const a = document.createElement('a');
  a.href = URL.createObjectURL(blob);
  a.download = 'audit-log.csv';
  a.click();
}

// In JSX — receives the already-filtered array, not the full dataset
<Button onClick={() => exportToCsv(filteredEvents)}>Export CSV</Button>;

​

Adding nuqs to a new page

1. Import useQueryState and the right parseAs* primitive.
2. Replace useState calls for filter values with useQueryState.
3. Keep the value in queryKey if it drives an API call.
4. Done — no adapter changes, no router wiring, no context setup.

// Before
const [status, setStatus] = useState('all');

// After — one import, one change
import { parseAsString, useQueryState } from 'nuqs';
const [status, setStatus] = useQueryState('status', parseAsString.withDefault('all'));

Caution: Do not mix useState and useQueryState for the same filter. If a filter is URL-persistent, it must only use useQueryState. Mixing the two creates split-brain state where the URL and component disagree after navigation.

​

Adding nuqs to a new portal

1. Add nuqs to the app’s package.json dependencies (it is already a workspace root dep).
2. Import NuqsAdapter from nuqs/adapters/next/app in the app’s providers.tsx.
3. Wrap children with <NuqsAdapter>.
4. All useQueryState calls in the app will work automatically.