Agent skill · software engineering · wsimmonds
nextjs-use-search-params-suspense
Pattern for using useSearchParams hook with Suspense boundary in Next.js. Covers the required combination of 'use client' directive and Suspense wrapper when accessing URL query parameters in client components. Use when building search interfaces, filters, pagination, or any feature that needs to read/manipulate URL query parameters client-side.
Why this skill is useful
Provides a specific pattern for using Next.js's useSearchParams with Suspense that includes client directives and async handling, which the AI may not generate accurately on its own.
What it needs
About 6k tokens when loaded. Last updated 2025-10-24. 109 stars on the source repository.
What this skill does
Next.js: useSearchParams with Suspense Pattern Pattern Overview The useSearchParams hook requires TWO things: 1. Component must have 'use client' directive 2. Component must be wrapped in a <Suspense> boundary This is a Next.js requirement, not optional! Why This Pattern? useSearchParams reads URL query parameters: /search?q=shoes → searchParams.get('q') returns "shoes" /products?category=electronics&sort=price → Read multiple params Why Suspense? Next.js uses React 18's Suspense to handle the async nature of reading URL params during server-side rendering and hydration. The Pattern Single-File Pattern (Recommended) Inline Pattern (Single File) Sometimes you want everything in one file: TypeScript: NEVER Use any Type Real-World Examples Example 1: Search Interface Example 2: Product Filters Example 3: Pagination Working with URLSearchParams Updating URL Parameters Common Patterns Pattern: Search with Debounce Pattern: Multiple Filters Common Mistakes ❌ Mistake 1: Missing 'use client' ❌ Mistake 2: Missing Suspense Wrapper ❌ Mistake 3: Using in Server Component Server vs Client searchParams Feature Server Component Client Component --------- ----------------- ------------------ Access method searchParams prop useSearchParams() hook Requires 'use client' ❌ No ✅ Yes Requires Suspense ❌ No ✅ Yes Can be async ✅ Yes ❌ No Can update params ❌ No (use Link/redirect) ✅ Yes (use router.push) Best for Initial load, SEO Dynamic filters, real-time updates Quick Checklist When using useSearchParams: [ ] Add 'use client' directive at top of file [ ] Import Suspense from 'react' [ ] Import useSearchParams from 'next/navigation' [ ] Wrap component using useSearchParams in <Suspense> [ ] Provide a fallback to Suspense [ ] Call useSearchParams() inside wrapped component [ ] Use .get(), .has(), or .getAll() to read params Summary useSearchParams with Suspense: ✅ Requires 'use client' directive ✅ Requires <Suspense> wrapper ✅ Use for client-side URL param reading ✅ Combine with useRouter( …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills wsimmonds/nextjs-use-search-params-suspense