API Reference

The library exposes a single class, exported as both default and named:

import Filter from '@kassaila/filter-dom-url';
// or
import { Filter } from '@kassaila/filter-dom-url';

new Filter(options)

interface FilterOptions {
  /** Selector used as `[${formAttr}]` to find the form. Pass the full attribute = value pair. */
  formAttr: string;
  /** Selector used as `[${filterAttr}]` to find every filter control inside the form. */
  filterAttr: string;
}

Example:

const filter = new Filter({
  formAttr: 'data-filter-form="example"',
  filterAttr: 'data-filter',
});

formAttr is the whole attribute selector body, including the value — that's what lets one page host multiple independent forms (data-filter-form="search", data-filter-form="results", …). filterAttr is just the attribute name; the param key per control is whatever value you put on data-filter="…".

The constructor only stores filterAttr and formAttr. It does not touch the DOM or window.location. Call init() after construction to resolve the form element, seed internal URL state, bind listeners, and apply the URL state to the DOM.

Instance methods

init(): void

• Resolves the form element ([${formAttr}]) and seeds internal url / urlFilters from window.location. Throws if the form selector does not match any element.
• Applies the current URL state to the form.
• Registers change listeners on every [filterAttr] control inside the form. These update the internal URLSearchParams only — they do not push to the actual URL. Call setFiltersToUrl to commit.
• Registers a popstate listener that resets the form and re-applies URL state.

updateDom(): void

Re-applies the cached URL state to the DOM. Call this if you mutated the URL outside the library (e.g. history.replaceState from your data layer) and want the form to follow.

setFiltersToUrl(newUrl: URL): void

Calls history.pushState with the current URLSearchParams merged onto newUrl. Use this to create an explicit history entry — typically from an "Apply" button.

resetUrl(): void

Removes every filter param the library knows about from the URL via pushState. Other params on the URL are preserved.

resetDom(): void

Calls form.reset(). Does not touch the URL.

destroy(): void

Removes all change event listeners that were attached to filter elements during init(), and removes the popstate listener from window. Call this when tearing down the instance — for example inside a framework component's unmount / onBeforeUnmount hook — to avoid memory leaks and stale event handlers.

const filter = new Filter({ formAttr: 'data-filter-form="example"', filterAttr: 'data-filter' });

filter.init();

// later, when the component unmounts:
filter.destroy();

getFilters(): Record<string, string[]>

Returns the current URL filters as a normalized object. Single-value filters come back as a one-item array. Param keys that don't correspond to any element with [filterAttr="<key>"] are dropped.

filter.getFilters();
// { topic: ['news', 'blog'], sort: ['popular'] }

Static helpers

Filter.checkFilterDomType($el: Element): FilterDomType | null

Maps a DOM element to its normalized filter type string.

type SupportedFilterDomType =
  | 'select-single'
  | 'select-multiple'
  | 'checkbox'
  | 'radio'
  | 'color'
  | 'range'
  | 'date'
  | 'month'
  | 'week'
  | 'time';

type FilterDomType = SupportedFilterDomType | (string & {});

Returns null if the element's tag is not <select> or <input>. Returns the input's type attribute value verbatim for any <input> — including unsupported types — so callers can differentiate "unknown but valid input" from "wrong tag entirely."

Types

export interface FilterOptions {
  filterAttr: string;
  formAttr: string;
}

export type SupportedFilterDomType =
  | 'select-single'
  | 'select-multiple'
  | 'checkbox'
  | 'radio'
  | 'color'
  | 'range'
  | 'date'
  | 'month'
  | 'week'
  | 'time';

export type FilterDomType = SupportedFilterDomType | (string & {});

export type FiltersMap = Record<string, string[]>;