wsimmonds/claude-nextjs-skills

Overview

This skill documents a clear pattern for using Next.js' useSearchParams hook inside client components together with a Suspense boundary. It explains why both the 'use client' directive and a Suspense wrapper are required and shows safe, TypeScript-friendly examples for search, filters, and pagination. The guidance focuses on practical code patterns and common pitfalls to avoid runtime errors during SSR/hydration.

How this skill works

useSearchParams is a client-only hook that reads URL query parameters at runtime. Because reading search params can be asynchronous across server and client rendering, Next.js requires the component that calls useSearchParams to include 'use client' and be rendered inside a React Suspense boundary with a fallback. Use useRouter for updating params and URLSearchParams to compose changes safely.

When to use it

• Building search interfaces that read query strings and update results dynamically.
• Implementing client-side filters or multi-selects that sync with the URL.
• Adding pagination that reads and writes the current page from query params.
• Creating inputs with debounced updates that reflect in the URL.
• Any feature that needs to read or mutate URL parameters on the client.

Best practices

• Always add 'use client' at the top of files using useSearchParams.
• Wrap the component that calls useSearchParams in <Suspense> and provide a fallback UI.
• Avoid using any for types; treat useSearchParams as ReadonlyURLSearchParams and type values explicitly.
• Create new URLSearchParams(searchParams.toString()) before modifying params to avoid mutating the original.
• Use router.push with the serialized params to update the URL; delete empty values to keep the URL clean.

Example use cases

• Search page: read q and category from query string and display results with a Suspense fallback.
• Product filters: keep category, sort, and price filters in the URL and update via router.push.
• Pagination: parse page from params, render posts for that page, and navigate with updated page param.
• Debounced search input: update q after a short delay and push params without flicker.