solid-query-state

Type-safe URL query state management for Solid.js. Sync component state with the URL search params—filters, pagination, modals, and more—with full TypeScript support and shareable links.

Installation

npm install solid-query-state
# or
pnpm add solid-query-state
# or
yarn add solid-query-state
# or
bun add solid-query-state

Requirements: Solid.js ^1, TypeScript ^5

Quick Start

1. Wrap your app with QueryStateAdapter:

import { render } from "solid-js/web";
import { QueryStateAdapter } from "solid-query-state";
import App from "./App";

render(
    () => (
        <QueryStateAdapter>
            <App />
        </QueryStateAdapter>
    ),
    document.getElementById("root")!,
);

2. Use createQueryState or createQueryStates in your components:

import { createQueryState, parseAsInteger } from "solid-query-state";

function Counter() {
    const [count, setCount] = createQueryState("count", parseAsInteger.withDefault(0));

    return (
        <div>
            <p>Count: {count()}</p>
            <button onClick={() => setCount((c) => (c ?? 0) + 1)}>+</button>
            <button onClick={() => setCount((c) => (c ?? 0) - 1)}>-</button>
        </div>
    );
}

Visiting ?count=5 will show 5; changing the count updates the URL. Back/forward navigation works as expected.

API

createQueryState

Manages a single query parameter. Returns a getter and setter (similar to createSignal).

const [value, setValue] = createQueryState("key", parser);

• key – URL parameter name (e.g. "page" → ?page=1)
• parser – Parses/serializes the value (see Built-in parsers)
• options – Optional: history, scroll, throttleMs, clearOnDefault, etc.

createQueryStates

Manages multiple query parameters at once.

const [state, setState] = createQueryStates({
    search: parseAsString.withDefault(""),
    page: parseAsInteger.withDefault(0),
    sort: parseAsStringLiteral(["asc", "desc"]),
});

Update one or more keys:

setState({ page: 1 });
setState((prev) => ({ page: (prev.page ?? 0) + 1 }));
setState(null); // clear all

Built-in parsers

| Parser | Type | Example | | --------------------------------- | ---------------- | ------------------------- | | parseAsString | string | ?q=hello | | parseAsInteger | number | ?page=1 | | parseAsFloat | number | ?lat=45.5 | | parseAsBoolean | boolean | ?active=true | | parseAsHex | number (hex) | ?color=ff0000 | | parseAsIndex | number (1-based) | ?tab=2 → index 1 | | parseAsTimestamp | Date (ms) | ?t=1700000000000 | | parseAsIsoDateTime | Date (ISO) | ?d=2024-01-01T00:00:00Z | | parseAsIsoDate | Date (date only) | ?d=2024-01-01 | | parseAsStringLiteral(["a","b"]) | union | ?mode=a | | parseAsStringEnum(values) | enum | same as above | | parseAsNumberLiteral([1,2,3]) | union of numbers | ?level=2 | | parseAsArrayOf(parser, ",") | array | ?tags=a,b,c |

All parsers support .withDefault(value) for default values. Keys are removed from the URL when set to their default (when clearOnDefault is true, which is the default).

Custom parsers

import { createParser } from "solid-query-state";

const parseAsJson = createParser({
    parse: (v) => {
        try {
            return JSON.parse(v);
        } catch {
            return null;
        }
    },
    serialize: (v) => JSON.stringify(v),
});

Options

Options can be passed to createQueryState / createQueryStates or per-parser via .withOptions():

| Option | Default | Description | | ----------------- | ----------- | ----------------------------------------------------------------------------- | | history | "replace" | "push" or "replace" for history updates | | scroll | false | Scroll to top on URL change | | throttleMs | 50 | Min ms between URL updates | | limitUrlUpdates | - | { method: "debounce", timeMs: 300 } or { method: "throttle", timeMs: 50 } | | clearOnDefault | true | Remove key from URL when value equals default |

Testing

Use SolidTestingAdapter or withSolidTestingAdapter to test components without a real browser URL:

import { render } from "@solidjs/testing-library";
import { createQueryState, parseAsString, withSolidTestingAdapter } from "solid-query-state";

const { getByTestId } = render(() => <MyComponent />, {
    wrapper: withSolidTestingAdapter({ searchParams: "?q=test" }),
});

License

MIT