feature-state-hook

state-in-url — Feature state hook

state-in-url stores a typed JSON-serializable object in the URL query string. State across components is shared by passing the same module-scoped default-state object to useUrlState. The library uses object identity, not deep equality, to wire up subscriptions — so the default state must be a static const, defined once, outside any component.

Setup

// features/jobs/jobsState.ts
export type JobsState = {
  status: '' | 'active' | 'closed';
  tab: 'details' | 'qa' | 'applicants';
  jobId: string;
};

export const JOBS_STATE: JobsState = {
  status: '',
  tab: 'details',
  jobId: '',
};

// features/jobs/useJobsState.ts
'use client';
import { useUrlState } from 'state-in-url/next';
import { JOBS_STATE } from './jobsState';

// `searchParams` comes from the server component at the top of the feature.
// Do not call useSearchParams() here — see the nextjs-ssr skill.
export function useJobsState(searchParams?: object) {
  return useUrlState(JOBS_STATE, { searchParams });
}

// app/jobs/page.tsx — server component
import { JobsTabs } from './JobsTabs';

export default async function Page({
  searchParams,
}: {
  searchParams: Promise<Record<string, string | string[] | undefined>>;
}) {
  return <JobsTabs searchParams={await searchParams} />;
}

// app/jobs/JobsTabs.tsx
'use client';
import { useJobsState } from 'features/jobs/useJobsState';

export function JobsTabs({ searchParams }: { searchParams?: object }) {
  const { urlState, setUrl, reset } = useJobsState(searchParams);

  return (
    <>
      <button onClick={() => setUrl({ tab: 'qa' })}>Q&A</button>
      <button onClick={reset}>Reset</button>
    </>
  );
}

The same useJobsState() called in two different components reads and writes the same URL state — no Context, no Provider. Only the component the server renders needs searchParams; the rest call useJobsState() with no argument.

Core Patterns