---
title: "filter-dom-url — keep form filter controls in sync with URL state"
description: "Tiny zero-dependency TS lib that wires inputs/selects to URLSearchParams and window.history. Sharable filter URLs without a framework."
url: https://symonov.com/projects/filter-dom-url/
---

# filter-dom-url

Tiny TypeScript library that keeps form filter controls in sync with URLSearchParams + history.

**2025** · by **Dmytro Symonov** · shipped · `typescript` `forms` `oss`

[docs](https://kassaila.github.io/filter-dom-url/) [github ↗](https://github.com/Kassaila/filter-dom-url) [npm ↗](https://www.npmjs.com/package/@kassaila/filter-dom-url)

## the problem

Filter UIs that change page state but live outside the URL are a UX trap: users can’t share links, can’t refresh without losing context, and back/forward buttons do the wrong thing. Most projects fix this with ad-hoc serialisation glue per page.

## the approach

A zero-dependency TypeScript library (< 1.5 KB min+brotli) that turns a plain `<form>` into a shareable, navigable, persistable filter UI — without a state library, without a router, without a framework. Form changes write to the URL via `history.pushState`; URL changes (including `popstate` from Back / Forward) replay back into the form.

Supports `select`, `select[multiple]`, and `<input>` types: checkbox, radio, color, range, date, month, week, time. Multi-value filters serialize as space-joined strings under a single param key. Ships ESM + CJS with bundled `.d.ts` declarations and sourcemaps.

## stack

- TypeScript, zero runtime dependencies
- ESM + CJS dual build
- Demo + docs on GitHub Pages

## links — external resources

- docs: [https://kassaila.github.io/filter-dom-url/](https://kassaila.github.io/filter-dom-url/)
- github: [https://github.com/Kassaila/filter-dom-url](https://github.com/Kassaila/filter-dom-url)
- npm: [https://www.npmjs.com/package/@kassaila/filter-dom-url](https://www.npmjs.com/package/@kassaila/filter-dom-url)