use-url-search-params

Built-in typed codecs for useUrlSearchParams schemas.


Package	`@vizejs/composable/use-url-search-params`
Own the source	`vize lib pull composable:use-url-search-params`
Runtime exports	`parseSearchParams`, `searchParam`, `serializeSearchParams`, `useUrlSearchParams`
Gzip budget	4096 B

Usage

import { parseSearchParams, searchParam, serializeSearchParams, useUrlSearchParams } from "@vizejs/composable/use-url-search-params";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`parseSearchParams`	state	experimental	safe	not-applicable	none	web, server, worker, native, desktop, terminal	`URL`, `URLSearchParams`	—
`serializeSearchParams`	state	experimental	safe	not-applicable	none	web, server, worker, native, desktop, terminal	`URL`, `URLSearchParams`	—
`useUrlSearchParams`	state	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, desktop	`window`	`parseSearchParams`, `serializeSearchParams`, `tryOnScopeDispose`

API

`searchParam`

Built-in typed codecs for useUrlSearchParams schemas.

const searchParam

`parseSearchParams`

Decode search parameters with a schema. Pure and SSR-safe.

function parseSearchParams<Schema extends SearchParamSchema>( schema: Schema, search: string | URL | URLSearchParams, ): InferSearchParams<Schema>

`serializeSearchParams`

Encode typed values with a schema. Pure and SSR-safe.

function serializeSearchParams<Schema extends SearchParamSchema>( schema: Schema, values: Partial<InferSearchParams<Schema>>, options: SerializeSearchParamsOptions = {}, ): URLSearchParams

`useUrlSearchParams`

Two-way bind typed URL search parameters described by a codec schema. Every property type is inferred from its codec. Assigning a property rewrites the query through history.replaceState (or pushState with mode: "push"), keeping parameters outside the schema and the fragment, and dropping values equal to their default. Back/forward navigation (popstate) re-reads the URL. Server rendering: no global is read. Pass ssrUrl (the request URL) so the server renders the same values the client reads during hydration. Inside a component the browser URL is first read after mounting, so the hydrating client renders the ssrUrl state before switching to it. Listeners are removed with the owning reactive scope or stop().

function useUrlSearchParams<const Schema extends SearchParamSchema>( schema: Schema, options: UseUrlSearchParamsOptions = {}, ): UrlSearchParamsControls<Schema>

const { params } = useUrlSearchParams({
  page: searchParam.number(1),
  sort: searchParam.enum(["new", "top"], "new"),
  tags: searchParam.array(),
});
params.page += 1; // ?page=2

Types

`SearchParamCodec`

Typed codec for one search parameter. parse receives every value of the key (URLSearchParams.getAll), which is empty when the key is absent; throwing selects default. serialize returns the values to write; an empty array removes the key.

Member	Type	Description
`default`	`Value`	Value used when the key is absent or unparsable.
`parse`	`(values: readonly string[]) => Value`	Decode all values of the key.
`serialize`	`(value: Value) => readonly string[]`	Encode a value to zero or more raw values.

`CustomSearchParam`

Single-value codec definition accepted by searchParam.custom.

Member	Type	Description
`parse`	`(raw: string) => Value`	Decode the first raw value. Throwing selects `default`.
`serialize`	`(value: Value) => string`	Encode a value to one raw value.
`default`	`Value`	Value used when the key is absent or unparsable.

`SerializeSearchParamsOptions`

Options for serializeSearchParams.

Member	Type	Description
`base`?	`string \| URL \| URLSearchParams`	Existing parameters to keep for keys outside the schema.
`removeDefaults`?	`boolean`	Omit keys whose value serializes like the codec default.

`UrlSearchParamsHost`

Minimal window surface used by useUrlSearchParams.

Member	Type	Description
`location`	`{ /** Query including the leading ?, or "". / readonly search: string; /* Fragment including the leading #, or "". / readonly hash: string; /* Path component. */ readonly pathname: string; }`	Current location; only the URL parts are read.
`history`	`{ /** Current history entry state, preserved when replacing. / readonly state: unknown; /* Replace the current entry's URL. / readonly replaceState: (data: unknown, unused: string, url: string) => void; /* Push a new entry with the given URL. */ readonly pushState: (data: unknown, unused: string, url: string) => void; }`	Session history used to write the query.

`UseUrlSearchParamsOptions`

Options for useUrlSearchParams.

Member	Type	Description
`host`?	`MaybeRefOrGetter<UrlSearchParamsHost \| null \| undefined>`	Browser host. `null`/`undefined` keeps server values.
`mode`?	`"replace" \| "push"`	History write mode for changes made through `params`.
`removeDefaults`?	`boolean`	Omit parameters equal to their codec default from the URL.
`ssrUrl`?	`MaybeRefOrGetter<string \| URL \| URLSearchParams \| undefined>`	Request URL used while no host is attached, so server markup matches the client's first render.

`UrlSearchParamsControls`

Reactive state and controls returned by useUrlSearchParams.

Member	Type	Description
`params`	`InferSearchParams<Schema>`	Writable typed parameters. Assign whole values (including new arrays); the object is shallowly reactive.
`supported`	`Readonly<Ref<boolean>>`	Whether a browser host is attached.
`refresh`	`() => void`	Re-read the current location.
`stop`	`() => void`	Stop following the URL. Idempotent; also runs on scope disposal.