Skip to content

Filter bar

A list's filters kept in the address as a GET form, working with no script or as you type.

<div data-mount="plain" id="sample-plain"></div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/filter-bar.css";
import { enhance } from "capsomer/behavior/filter-bar";

enhance();

Usage

<form method="get" role="search" aria-label="Filter payments" class="cap-filter-bar" data-cap="filter-bar">
  <div class="cap-filter-bar-fields">[fields]</div>
  <div class="cap-filter-bar-actions">
    <button type="submit" class="cap-btn">Apply</button>
    <a class="cap-btn" href="/payments">Clear filters</a>
  </div>
  <p class="cap-filter-bar-count" role="status">12 of 40 payments</p>
</form>

Examples

Applies as you type

<div data-mount="live" id="sample-live"></div>

Nothing filtered

<div data-mount="empty" id="sample-empty"></div>

API reference

FilterBar

PropTypeRequiredDoes
labelstringYesThe landmark's name: "Filter payments".
childrenReactNodeYesThe fields: Capsomer field, select, segmented, range, chips.
countReactNodeThe count line ("Showing 12 of 40 payments", countText from capsomer/content) or null.
clearHrefstring | nullThe address with the filters cleared, or null when nothing is filtered (Clear is hidden).
FormFormLike | "form"The form to render: React Router's Form keeps a client navigation; a plain form otherwise.
actionstring
liveboolean
delaynumber
applyLabelstring
applyVariant"default" | "primary""primary" when Apply is the view's main action (a search page); the default button otherwise.
clearLabelstring
renderLink(props: { href: string; className: string; children: ReactNode }) => ReactNodeThe link Clear renders, for a router link (capsomer/react/link Link); a plain a otherwise.
onSubmit(e: FormEvent<HTMLFormElement>) => voidFor an app whose router is not React Router (a wouter SPA): handle the submit yourself, read the fields with new FormData(e.currentTarget) and navigate. Call e.preventDefault().
classNamestring

Functions

FunctionSignatureDoes
withParams(path: string, params: Params, defaults?: Params): stringpath with params as its query, leaving out empty values and any value equal to its default (defaults), so the address stays short and one view has one address.
clearedHref(path: string, params: Params, keep?: readonly string[]): stringThe address with only keep left (a sort and a page size survive Clear; the filters go).
isFiltered(params: Params, keys: readonly string[], defaults?: Params): booleanTrue when any of keys has a value in params that differs from its default.
liveSubmit(form: HTMLFormElement, delay?: number): () => voidSubmits form after typing stops in a text field, at once when a select, a checkbox or a radio changes. While an IME is composing ("ni hao" before it becomes 你好) nothing is sent; the end of the composition counts as typing. Returns the function that detaches.
enhance(root?: ParentNode): () => voidAttaches liveSubmit to every form[data-cap="filter-bar"][data-live] under root.

Parts and data attributes

ClassIs
.cap-filter-barthe root
.cap-filter-bar-actionsa part
.cap-filter-bar-counta part
.cap-filter-bar-fieldsa part

Accessibility

KeyDoes
TabThrough the fields, Apply, Clear
Enter in a fieldApplies
  • A search landmark with a name; each field has its label; the count is announced politely.
  • Screen readers: no manual NVDA or VoiceOver run, by decision (2026-11-07); the automated browser checks and a front-end review stand in. Automated: see the site's Tests page.