input-handling

This skill builds on state-in-url/feature-state-hook. Read it first for the module-scoped default-state rule.

state-in-url — Input handling

useUrlState returns three setters with different timing:

Setter	What updates	When
setState(value)	Internal state only	Synchronous
setUrl(value)	Internal state + URL	State sync, URL on next tick (throttled)
setUrl()	Flush current state to URL	URL on next tick (diff-checked, no-op if equal)

State updates always render immediately. URL writes are coalesced through an internal global timer (TIMEOUT constant in useUrlStateBase.ts) so a burst of setUrl calls produces one URL update.

Setup

// features/search/searchState.ts
export type SearchState = { q: string; sort: 'name' | 'date' };
export const SEARCH_STATE: SearchState = { q: '', sort: 'name' };

// features/search/useSearchState.ts
'use client';
import { useUrlState } from 'state-in-url/next';
import { SEARCH_STATE } from './searchState';

// `searchParams` comes from the server component at the top of the feature.
export function useSearchState(searchParams?: object) {
  return useUrlState(SEARCH_STATE, { searchParams });
}

// app/search/page.tsx — server component
import { SearchBox } from './SearchBox';

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

Core Patterns

Instant input, deferred URL write (onBlur)

'use client';

function SearchBox({ searchParams }: { searchParams?: object }) {
  const { urlState, setState, setUrl } = useSearchState(searchParams);

  return (
    <input
      value={urlState.q}
      onChange={(e) => setState({ q: e.target.value })}
      onBlur={() => setUrl()}
    />
  );
}