@echojs-ecosystem/url-state

Type-safe URL search params — nuqs-style, signal-native.

Manage query string state with typed parsers, defaults, and router integration. Built for EchoJS signals — no React hooks.

Features

• createQueryParam — single typed param
• createQueryParams — object of params with batch updates
• Rich parsers — string, int, float, bool, literal, array, JSON + Standard Schema
• Router adapter — auto-sync with @echojs-ecosystem/router/hyperdom
• History control — push / replace per update
• urlKeys — remap param names in the URL

Install

npm install @echojs-ecosystem/url-state @echojs-ecosystem/reactivity

Quick start

import {
  createQueryParams,
  parseAsInteger,
  parseAsString,
  parseAsBoolean,
} from "@echojs-ecosystem/url-state";

const filters = createQueryParams({
  q: parseAsString.withDefault(""),
  page: parseAsInteger.withDefault(1),
  inStock: parseAsBoolean.withDefault(false),
});

filters.value(); // { q: "", page: 1, inStock: false }
filters.set({ q: "bike", page: 2 });
filters.update((v) => ({ ...v, page: v.page + 1 }));
filters.reset();

With router

import { createRouter } from "@echojs-ecosystem/router/hyperdom";

export const appRouter = createRouter({ routes });

export const filters = appRouter.createQueryParams({
  q: parseAsString.withDefault(""),
  page: parseAsInteger.withDefault(1),
});

Parsers

| Parser | Example | |--------|---------| | parseAsString | ?q=hello | | parseAsInteger / parseAsFloat | ?page=2 | | parseAsBoolean | ?open=true | | parseAsLiteral(["a","b"]) | Enum values | | parseAsArrayOf | ?tag=a&tag=b | | parseAsJson(schema) | Complex objects |

Related packages

| Package | Role | |---------|------| | @echojs-ecosystem/router | SPA URL sync | | @echojs-ecosystem/reactivity | Signal-backed param state |

Documentation

echojs.dev/docs/packages/url-state