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.

packages.vue bound to this page's URL
q · stringCodec({ maxLength: 40 })
view · enumCodec
page · numberCodec({ min: 1, max: 99 })
1
tags · arrayCodec({ invalidItems: 'drop' })
keyin the URLtyped valuetype
The URL has no keys, so every ref holds its default. Type in the bar above, or use the controls.
0ref writes
0navigations
0issues

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.

ref writenavigation

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=50

Cross-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=60000

Typed and checked.

Hover the code: every type comes from the package itself, and every rule runs when a link is opened.

useQueryStateone key, one ref
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.
@example```ts const page = useQueryState('page', numberCodec({ default: 1, int: true, min: 1 })) page.value++ // ?page=2 ```
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=2
useQueryStatesseveral keys, one object
const 
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.
@example```ts const table = useQueryStates({ prefix: 'users', schema: { page: numberCodec({ default: 1, int: true, min: 1 }), pageSize: numberCodec({ default: 20, min: 10, max: 100, outOfRange: 'clamp' }), }, urlKeys: { pageSize: 'size' }, }) ```
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'],
}, }, })
schemaCodecan object in one key
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.
@example```ts const page = useQueryState('page', numberCodec({ default: 1, int: true, min: 1 })) page.value++ // ?page=2 ```
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
/
0ref writes
0navigations
  1. Navigations appear here.
Writes made in the same tick, from any component, become one navigation.

Make every screen a link.

Copyright © 2026 Cyprien Thao. Released under the MIT License.