Loading...
Loading...
URL search param and hash state management. Use when adding or modifying URL search params, working with useSearchParams, setSearchParams, useSearchParamState, or navigate() with query strings or hash fragments, or fixing browser back/forward button issues.
npx skill4agent add promptfoo/promptfoo search-params| Change type | Examples | History behavior |
|---|---|---|
| In-page state | Filters, sort, pagination, tab switches, search queries | |
| Navigable step | Wizard progression, multi-step forms | |
| Unsure? | Ask the developer before choosing |
useSearchParamStatereplace: trueimport { useSearchParamState } from '@app/hooks/useSearchParamState';
import { z } from 'zod';
const TabSchema = z.enum(['overview', 'details', 'settings']);
const [activeTab, setActiveTab] = useSearchParamState('tab', TabSchema, 'overview');src/app/src/hooks/useSearchParamState.tssetSearchParamsreplace: truesetSearchParams{ replace: true }const [searchParams, setSearchParams] = useSearchParams();
// Updating filters (in-page state -> replace)
setSearchParams(
(params) => {
params.set('status', 'active');
params.set('sort', 'name');
return params;
},
{ replace: true },
);navigate()// Wizard step navigation - push so back button works between steps
// See: src/app/src/pages/redteam/setup/page.tsx
const updateHash = (newStep: string) => {
navigate(`#${newStep}`); // push (default) - intentional
};// Tab switch on a detail page - replace to avoid history clutter
navigate(`#${section}`, { replace: true });// After first save, update URL to include new ID without adding history entry
navigate(`/evals/${newConfigId}`, { replace: true });// WRONG - every filter change adds a history entry
setSearchParams((params) => {
params.set('filter', value);
return params;
});
// WRONG - navigate without replace for state change
navigate(`?tab=${newTab}`);useSearchParams// WRONG - no validation, easy to forget { replace: true }
const [searchParams, setSearchParams] = useSearchParams();
const tab = searchParams.get('tab');
const setTab = (v: string) => {
setSearchParams((p) => {
p.set('tab', v);
return p;
});
};
// RIGHT - use the hook instead
const [tab, setTab] = useSearchParamState('tab', TabSchema, 'overview');// WRONG - useSearchParamState will throw an invariant error
setTab('');
// RIGHT - use null to clear a param
setTab(null);src/app/src/hooks/useSearchParamState.tssrc/app/src/pages/eval/components/ResultsView.tsx{ replace: true }src/app/src/pages/redteam/setup/page.tsx