url-state-patterns
Sync React state to URL query params with nuqs (Suspense wrapper, parsers, clearing, deep-linkable dialogs). Use when building shareable filters, search, or URL-driven dialogs.
How do I install this agent skill?
npx skills add https://github.com/andrelandgraf/fullstackrecipes --skill url-state-patternsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides architectural patterns for synchronizing React state with URL query parameters using the nuqs library. It includes instructional code for Suspense wrappers, state parsing, and deep-linkable dialogs with no security issues detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
URL State Patterns
Sync React state to URL query params with nuqs.
Prerequisites
Complete these setup recipes first:
- URL State with nuqs
Suspense Wrapper
nuqs reads useSearchParams, so it needs a Suspense boundary. Colocate it by exporting a public wrapper that suspends an internal client component — consumers then use the component without adding Suspense themselves.
import { Suspense } from "react";
type SearchInputProps = { placeholder?: string };
export function SearchInput(props: SearchInputProps) {
return (
<Suspense fallback={<input placeholder={props.placeholder} disabled />}>
<SearchInputClient {...props} />
</Suspense>
);
}
"use client";
import { useQueryState, parseAsString } from "nuqs";
function SearchInputClient({ placeholder = "Search..." }: SearchInputProps) {
const [search, setSearch] = useQueryState("q", parseAsString.withDefault(""));
return (
<input
value={search}
onChange={(e) => setSearch(e.target.value || null)}
placeholder={placeholder}
/>
);
}
Parsers
Replace useState with useQueryState plus a parser. Use .withDefault() to read a fallback while keeping the URL clean.
"use client";
import {
useQueryState,
parseAsString,
parseAsBoolean,
parseAsArrayOf,
} from "nuqs";
const [search, setSearch] = useQueryState("q", parseAsString.withDefault(""));
const [showArchived, setShowArchived] = useQueryState(
"archived",
parseAsBoolean.withDefault(false),
);
const [tags, setTags] = useQueryState(
"tags",
parseAsArrayOf(parseAsString).withDefault([]),
);
Clearing
Set a value to null to remove it from the URL. With .withDefault(), the param clears but reads return the default.
setSearch(null);
function clearFilters() {
setSearch(null);
setTags(null);
setShowArchived(null);
}
Deep-Linkable Dialogs
Drive dialog visibility from a URL param so it's shareable and survives back/forward. Wrap in the same Suspense pattern.
import { Suspense } from "react";
type DeleteDialogProps = { onDelete: (id: string) => Promise<void> };
export function DeleteDialog(props: DeleteDialogProps) {
return (
<Suspense fallback={null}>
<DeleteDialogClient {...props} />
</Suspense>
);
}
"use client";
import { useQueryState, parseAsString } from "nuqs";
import { AlertDialog, AlertDialogContent } from "@/components/ui/alert-dialog";
function DeleteDialogClient({ onDelete }: DeleteDialogProps) {
const [deleteId, setDeleteId] = useQueryState("delete", parseAsString);
async function handleDelete() {
if (!deleteId) return;
await onDelete(deleteId);
setDeleteId(null);
}
return (
<AlertDialog open={!!deleteId} onOpenChange={(open) => !open && setDeleteId(null)}>
<AlertDialogContent>
<Button onClick={handleDelete}>Delete</Button>
</AlertDialogContent>
</AlertDialog>
);
}
Open it from anywhere by setting the param — setDeleteId("item-123") yields the deep link /items?delete=item-123.
function ItemRow({ item }: { item: Item }) {
const [, setDeleteId] = useQueryState("delete", parseAsString);
return (
<Button variant="ghost" onClick={() => setDeleteId(item.id)}>
Delete
</Button>
);
}
References
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/andrelandgraf/fullstackrecipes/url-state-patterns">View url-state-patterns on skillZs</a>