use-route-query

Built-in QueryParsers.

Usage

import { queryParsers, oneOf, useRouteQuery, useRouteParams } from "@vizejs/composable/use-route-query";

Runtime contract

API

queryParsers

Built-in QueryParsers.

const queryParsers

oneOf

Parser accepting only the given literal values.

function oneOf<const Values extends readonly string[]>( values: Values, ): QueryParser<Values[number]>

useRouteQuery(route, "sort", { parse: oneOf(["new", "top"]), default: "new" });

useRouteQuery

Typed, optionally writable view of one query parameter. The value type is inferred from parse and default: with a default the ref never holds undefined. Pass navigate to make the ref writable; writes build the next query (keeping every other key), drop the key when the value equals the default, and hand it to navigate, which is where the router integration pushes or replaces the URL. Works with any route object exposing query, including @vizejs/router's RouteMatch. Pure derived state: SSR-safe and hydration-stable (it reads the matched route only).

function useRouteQuery( route: MaybeRefOrGetter<RouteLocationLike>, key: string, options: StringQueryOptions & { readonly default: string; readonly navigate: (query: RouteQueryRecord) => void; }, ): WritableComputedRef<string>

const page = useRouteQuery(match, "page", {
  parse: queryParsers.integer,
  default: 1,
  navigate: (query) => navigateTo(router.resolve(match.value.name, match.value.params, { query })),
});
page.value += 1;

useRouteQuery

function useRouteQuery( route: MaybeRefOrGetter<RouteLocationLike>, key: string, options: StringQueryOptions & { readonly navigate: (query: RouteQueryRecord) => void }, ): WritableComputedRef<string | undefined, string | undefined>

useRouteQuery

function useRouteQuery( route: MaybeRefOrGetter<RouteLocationLike>, key: string, options: StringQueryOptions & { readonly default: string }, ): ComputedRef<string>

useRouteQuery

function useRouteQuery( route: MaybeRefOrGetter<RouteLocationLike>, key: string, options?: StringQueryOptions, ): ComputedRef<string | undefined>

useRouteQuery

function useRouteQuery<Value>( route: MaybeRefOrGetter<RouteLocationLike>, key: string, options: UseRouteQueryOptions<Value> & { readonly default: NoInfer<Value>; readonly navigate: (query: RouteQueryRecord) => void; }, ): WritableComputedRef<Value>

useRouteQuery

function useRouteQuery<Value>( route: MaybeRefOrGetter<RouteLocationLike>, key: string, options: UseRouteQueryOptions<Value> & { readonly navigate: (query: RouteQueryRecord) => void }, ): WritableComputedRef<Value | undefined, Value | undefined>

useRouteQuery

function useRouteQuery<Value>( route: MaybeRefOrGetter<RouteLocationLike>, key: string, options: UseRouteQueryOptions<Value> & { readonly default: NoInfer<Value> }, ): ComputedRef<Value>

useRouteQuery

function useRouteQuery<Value>( route: MaybeRefOrGetter<RouteLocationLike>, key: string, options: UseRouteQueryOptions<Value>, ): ComputedRef<Value | undefined>

useRouteQuery

function useRouteQuery( route: MaybeRefOrGetter<RouteLocationLike>, key: string, options: ErasedQueryOptions = {}, ): ComputedRef<unknown> | WritableComputedRef<unknown>

useRouteParams

Typed view of the matched route's path params. Without a key, returns all params (typed from the route table when the route comes from @vizejs/router). With a key, returns that param; with a parser, the parsed value. Pure derived state: SSR-safe.

function useRouteParams<Route extends RouteLocationLike>( route: MaybeRefOrGetter<Route>, ): ComputedRef<RouteParamsOf<Route>>

const params = useRouteParams(match); // ComputedRef<{ readonly id: string }>
const id = useRouteParams(match, "id", Number); // ComputedRef<number>

useRouteParams

function useRouteParams<Route extends RouteLocationLike, Key extends keyof Route["params"]>( route: MaybeRefOrGetter<Route>, key: Key, ): ComputedRef<Route["params"][Key]>

useRouteParams

function useRouteParams< Route extends RouteLocationLike, Key extends keyof Route["params"], Value, >( route: MaybeRefOrGetter<Route>, key: Key, parse: (raw: Route["params"][Key]) => Value, ): ComputedRef<Value>

useRouteParams

function useRouteParams( route: MaybeRefOrGetter<RouteLocationLike>, ...args: readonly [] | readonly [PropertyKey] | readonly [PropertyKey, (raw: unknown) => unknown] ): ComputedRef<unknown>

Types

RouteLocationLike

Structural subset of a matched route. @vizejs/router's RouteMatch satisfies it, so its inferred params type flows through without this package depending on the router.

UseRouteQueryOptions

Options for useRouteQuery.