Skip to content

Search Parameters

A lesson filter belongs in the URL when readers should be able to bookmark or share it. Search parameters are the key/value pairs after ?; they do not select the pathname route, but your page can read them to choose what to display.

Use useSearchParams inside a registered page or middleware. It returns a URLSearchParams snapshot for the rendered route and a setter that starts native navigation. This is not local React state with a synchronous setter.

In a page already registered at /lessons, read the filter and give absence an explicit meaning:

import { useSearchParams } from '@studiolambda/router/react'
export default function LessonFilterSummary() {
const [searchParams] = useSearchParams()
const topic = searchParams.get('topic') ?? 'all'
return <p>Topic: {topic}</p>
}

At /lessons?topic=react, this renders Topic: react. Without topic, it renders Topic: all. An explicitly empty ?topic= stays an empty string because ?? only handles absence. URLSearchParams performs query decoding; this differs from the encoded values returned by useParams() for pathname captures.

Treat every query value as untrusted input. Validate enums, numeric bounds, and identifiers before they affect requests. Do not store secrets in the URL: URLs can appear in history, logs, copied links, and referrers.

Change one value without discarding the rest

Section titled “Change one value without discarding the rest”

When a filter control shares the query string with pagination or display settings, use the updater form. It receives a freshly parsed mutable query object:

import { useSearchParams } from '@studiolambda/router/react'
export default function ReactTopicButton() {
const [, setSearchParams] = useSearchParams()
function onClick() {
try {
const result = setSearchParams((current) => {
current.set('topic', 'react')
current.delete('page')
return current
})
Promise.all([result.committed, result.finished]).catch(console.error)
} catch (error) {
console.error(error)
}
}
return <button onClick={onClick}>Show React lessons</button>
}

At /lessons?view=compact&page=3#list, this navigates to /lessons?view=compact&topic=react#list. The hash survives. The default history behavior is 'replace', so repeated filter changes do not automatically create a long Back history. Navigation guards and prefetch still participate in an eligible query-only navigation.

The setter also accepts a record or a URLSearchParams object. Every form replaces the whole query string with the returned value. In the preceding component, these alternatives mean:

const result = setSearchParams({ topic: 'react' }, { history: 'push' })
Promise.all([result.committed, result.finished]).catch(console.error)

This drops all old query keys, preserves the hash, and creates a new history entry. Use it for a deliberate search submission where Back should restore the previous search. Use an empty object or empty URLSearchParams to remove the query altogether. Use URLSearchParams.append/getAll for repeated keys; a plain string record represents one value per key.

Mutating the getter from useSearchParams() alone does not navigate. Return changed params through the setter. Setter/updater exceptions propagate synchronously, while native failures reject its NavigationResult; handle both as shown above.

The getter derives from Router’s React URL state, not the mutable browser entry. This keeps components in one render on the same location snapshot. After a failed noncancelable traversal, rendered params can therefore differ from the address bar; see commit ordering.

The updater also starts from that rendered URL snapshot. It is not a queued React state reducer that guarantees merging several rapid, uncommitted setter calls. Combine related changes in one updater instead of issuing several navigations that depend on one another.

The fixed memory navigation adapter returns resolved results without changing the URL, so it does not exercise interactive filter updates. Use a native browser or an event-capable test adapter to verify navigation behavior.