ref(),
but in the URL.
Typed query-string state for Vue and vue-router. Edit the URL in the console, or the controls under it.
| key | in the URL | typed value | type |
|---|---|---|---|
| The URL has no keys, so every ref holds its default. Type in the bar above, or use the controls. | |||
Built for screens
people share.
Filters, tabs, pages and open panels belong in the URL. Bind them once, and reload, Back, and shared links all restore the screen.
One tick, one navigation
Every write made in the same tick, from any component, lands as a single router.replace. Guards run once, and Back gets one entry.
Rules on every key
min, max, int, lengths, patterns, enums. A value that breaks a rule falls back to the default, or is clamped when you ask.
numberCodec({ default: 1, min: 1 })Grouped keys
Several keys behind one object, under a prefix, written together.
?users.page=2&users.size=50Cross-field rules
Name a rule, the keys it reads, and the keys it rejects. from <= to, min <= max.
reject: ['salaryMax']Keys from your data
Filters a user builds at runtime get their own keys with dynamicQueryState.
?f.fields.salary~gte=60000Typed and checked.
Hover the code: every type comes from the package itself, and every rule runs when a link is opened.
const const page: WritableComputedRef<number, number>page = useQueryState<QueryCodec<number, number>>(key: string, codec: QueryCodec<number, number>): WritableComputedRef<number, number>Binds one query-string key to a writable computed ref, typed by its codec.
Reads come from the shared client cache. Writes are normalized through the codec,
then batched with every other write of the tick into one navigation.useQueryState(
'page',
numberCodec<{
readonly default: 1;
readonly int: true;
readonly min: 1;
}>(options?: {
readonly default: 1;
readonly int: true;
readonly min: 1;
} | undefined): QueryCodec<number, number>
Finite numbers. `?page=abc`, `?page=` and `?page=Infinity` are rejected.numberCodec({ default: 1default: 1, int: trueint: true, min: 1min: 1 }),
)
const page: WritableComputedRef<number, number>page.Ref<number, number>.value: numbervalue++ // ?page=2const const salary: WritableComputedRef<{
min: number | undefined;
max: number | undefined;
}, {
min: number | undefined;
max: number | undefined;
}>
salary = useQueryStates<{
min: QueryCodec<number, number | undefined>;
max: QueryCodec<number, number | undefined>;
}, {
readonly range: readonly ["min", "max"];
}>(options: UseQueryStatesOptions<{
min: QueryCodec<number, number | undefined>;
max: QueryCodec<number, number | undefined>;
}, {
readonly range: readonly ["min", "max"];
}>): WritableComputedRef<{
min: number | undefined;
max: number | undefined;
}, {
min: number | undefined;
max: number | undefined;
}>
Binds several keys to one writable object. Assigning a new object writes every key in
one navigation.useQueryStates({
UseQueryStatesOptions<{ min: QueryCodec<number, number | undefined>; max: QueryCodec<number, number | undefined>; }, { readonly range: readonly ["min", "max"]; }>.schema: {
min: QueryCodec<number, number | undefined>;
max: QueryCodec<number, number | undefined>;
} & ValidSchema<{
min: QueryCodec<number, number | undefined>;
max: QueryCodec<number, number | undefined>;
}>
One entry per property: a codec, or a `dynamicQueryState(...)`.schema: {
min: QueryCodec<number, number | undefined>min: numberCodec<{
readonly min: 0;
}>(options?: {
readonly min: 0;
} | undefined): QueryCodec<number, number | undefined>
Finite numbers. `?page=abc`, `?page=` and `?page=Infinity` are rejected.numberCodec({ min: 0min: 0 }),
max: QueryCodec<number, number | undefined>max: numberCodec<{
readonly min: 0;
}>(options?: {
readonly min: 0;
} | undefined): QueryCodec<number, number | undefined>
Finite numbers. `?page=abc`, `?page=` and `?page=Infinity` are rejected.numberCodec({ min: 0min: 0 }),
},
UseQueryStatesOptions<{ min: QueryCodec<number, number | undefined>; max: QueryCodec<number, number | undefined>; }, { readonly range: readonly ["min", "max"]; }>.rules?: QueryStatesRules<QueryStatesValue<{
min: QueryCodec<number, number | undefined>;
max: QueryCodec<number, number | undefined>;
}>, {
readonly range: readonly ["min", "max"];
}> | undefined
Cross-field rules, checked when the URL is read.rules: {
range: {
keys: readonly ["min", "max"];
check: (values: DefinedValues<QueryStatesValue<{
min: QueryCodec<number, number | undefined>;
max: QueryCodec<number, number | undefined>;
}>, "min" | "max">) => boolean;
reject: readonly ("min" | "max")[];
message?: string;
}
range: {
keys: readonly ["min", "max"]Keys the rule reads. The rule is skipped while any of them is `undefined`.keys: ['min', 'max'],
check: (values: DefinedValues<QueryStatesValue<{
min: QueryCodec<number, number | undefined>;
max: QueryCodec<number, number | undefined>;
}>, "min" | "max">) => boolean
Return `false` to reject. Values are typed and never `undefined`.check: ({ min: numbermin, max: numbermax }) => min: numbermin <= max: numbermax,
reject: readonly ("min" | "max")[]Keys that fall back to their default when the check fails. Must be among `keys`.reject: ['max'],
},
},
})const const sort: WritableComputedRef<{
key: string;
direction: "asc" | "desc";
}, {
key: string;
direction: "asc" | "desc";
}>
sort = useQueryState<QueryCodec<{
key: string;
direction: "asc" | "desc";
}, {
key: string;
direction: "asc" | "desc";
}>>(key: string, codec: QueryCodec<{
key: string;
direction: "asc" | "desc";
}, {
key: string;
direction: "asc" | "desc";
}>): WritableComputedRef<{
key: string;
direction: "asc" | "desc";
}, {
key: string;
direction: "asc" | "desc";
}>
Binds one query-string key to a writable computed ref, typed by its codec.
Reads come from the shared client cache. Writes are normalized through the codec,
then batched with every other write of the tick into one navigation.useQueryState(
'sort',
schemaCodec<z.ZodObject<{
key: z.ZodString;
direction: z.ZodEnum<{
asc: "asc";
desc: "desc";
}>;
}, z.core.$strip>, {
readonly default: {
readonly key: "name";
readonly direction: "asc";
};
}>(schema: z.ZodObject<{
key: z.ZodString;
direction: z.ZodEnum<{
asc: "asc";
desc: "desc";
}>;
}, z.core.$strip>, options?: {
readonly default: {
readonly key: "name";
readonly direction: "asc";
};
} | undefined): QueryCodec<{
key: string;
direction: "asc" | "desc";
}, {
key: string;
direction: "asc" | "desc";
}>
A structured value in one key, typed and checked by any Standard Schema library (Zod,
Valibot, ArkType...). The schema is the rule, so there is no `validate`. The URL format is
JSON unless `format` says otherwise. Synchronous schemas only.schemaCodec(
import zz.function object<{
key: z.ZodString;
direction: z.ZodEnum<{
asc: "asc";
desc: "desc";
}>;
}>(shape?: {
key: z.ZodString;
direction: z.ZodEnum<{
asc: "asc";
desc: "desc";
}>;
} | undefined, params?: string | {
error?: string | z.core.$ZodErrorMap<NonNullable<z.core.$ZodIssueInvalidType<unknown> | z.core.$ZodIssueUnrecognizedKeys>> | undefined;
message?: string | undefined | undefined;
} | undefined): z.ZodObject<{
key: z.ZodString;
direction: z.ZodEnum<{
asc: "asc";
desc: "desc";
}>;
}, z.core.$strip>
object({
key: z.ZodStringkey: import zz.function string(params?: string | z.core.$ZodStringParams): z.ZodString (+1 overload)string(),
direction: z.ZodEnum<{
asc: "asc";
desc: "desc";
}>
direction: import zz.enum<readonly ["asc", "desc"]>(values: readonly ["asc", "desc"], params?: string | z.core.$ZodEnumParams): z.ZodEnum<{
asc: "asc";
desc: "desc";
}> (+1 overload)
export enum
enum(['asc', 'desc']),
}),
{ default: {
readonly key: "name";
readonly direction: "asc";
}
default: { key: "name"key: 'name', direction: "asc"direction: 'asc' } },
),
)
// ?sort={"direction":"desc","key":"date"}Three writes.
One navigation.
One client per router sits between your refs and vue-router. It updates every bound ref at once, then flushes the tick to the URL.
How batching works- Navigations appear here.