Query String Adapter

A query string adapter stores data in the URL’s search parameters. This demonstrates how nanostores-storage’s adapter pattern can be extended to any synchronous storage backend.

Live Demo

Try changing values and watch the URL update in real-time. Use the mode toggle to see the difference between pushState and replaceState.

Implementation

Query string adapters are not included in the library — you need to implement your own. This demo uses URLSearchParams for parsing and the History API for URL updates.

See the demo source code above for a complete implementation example.

History Mode Options

pushState (creates history entries)

const adapter = createQueryStringAdapter({ mode: "push" });

// Each change adds to browser history
// User can use back/forward buttons to navigate

Best for:

Multi-step wizards or forms
When users expect back button to undo changes
Navigation-like state changes

replaceState (no history entries)

const adapter = createQueryStringAdapter({ mode: "replace" });

// Updates URL without adding history entries
// Cleaner for frequent updates

Best for:

Filter/sort state that changes frequently
Search inputs with debounced updates
Transient UI state

Usage

import { createStorageStore } from "@vp-tw/nanostores-storage";

const qsAdapter = createQueryStringAdapter({ mode: "replace" });

// Single value store
const filterStore = createStorageStore(qsAdapter, "filter", {
  defaultValue: "all",
  listen: true, // Sync on popstate
});

// Use in your app
filterStore.set("active"); // URL: ?filter=active

Limitations

Combining with Other Adapters

Use as a fallback to persist important state in the URL:

import { createStorageStore, sessionStorageAdapter } from "@vp-tw/nanostores-storage";

const qsAdapter = createQueryStringAdapter({ mode: "replace" });

// URL is checked first, sessionStorage as fallback
const tabStore = createStorageStore([qsAdapter, sessionStorageAdapter], "tab", {
  defaultValue: "overview",
});