Filter
Filter form for collections. A <form> wrapper that arranges arbitrary form controls into a predictable filter panel with a submit button, optional clear action, and a live summary of the currently selected filters. The component is a layout shell - it does not manage state or perform filtering, so the consumer is free to wire it to their own backend or AJAX handler.
Usage
When to use
- A listing page needs a persistent filter panel next to the results
- Users must combine multiple criteria (facets, ranges, keywords) before submitting
- The selected filters should be summarized back to the user as chips
When not to use
- For a single search field - use a simple search component
- For instant filtering with no submit step - consider a dedicated combobox or faceted search pattern
- When the page needs only one control - a plain
<select>will do
Do
- Group related controls inside
<fieldset>with a<legend> - Provide a clear action that is reversible or confirmed
- Keep the panel scannable - short labels, sensible defaults
Don't
- Don't hide critical filters behind progressive disclosure on desktop
- Don't trigger destructive resets without a confirmation
API
Slots
| Slot | Required | Description |
|---|---|---|
content | Yes | HTML string for the inner contents of the filter panel, including groups, selected chips, and actions. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.subtle | Emphasis | - | Lower emphasis; a muted, quieter weight. |
.neutral | Emphasis | Yes | Default emphasis; the standard weight at balanced contrast. |
.accent | Emphasis | - | Higher emphasis; a stronger, louder weight. |
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.horizontal | Orientation | - | Children flow along the horizontal axis. |
.vertical | Orientation | Yes | Children flow along the vertical axis. |
.sticky | Position | - | Pins the component to a viewport edge while scrolling. |
.flat | Elevation | Yes | No elevation. |
.raised | Elevation | - | Slight elevation. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-filter | Consumer | Yes | Marks the filter form root; the change-announcement and chip-driven-uncheck behaviors bind to it. |
data-filter-selected | Consumer | - | Marks the selected-chips summary region where the behavior materializes and removes chips. |
data-chip | Consumer | - | Owned by the chip component; the filter sets it on chips it generates and matches it to recognize chips in the selected region. |
data-close | Consumer | - | Set by the filter on the injected dismiss button inside a generated chip so the close utility wires up its dismiss interaction. |
Events
| Event | Direction | Description |
|---|---|---|
filter-change | Emits | Fired on the form before the script acts on a control change, a selected chip dismissal, or a reset. detail.reason says which of the three produced it. Carries a null control and parent for a reset, which has no single source control. Cancelable - preventDefault() skips the aria-live tagging and chip materialization on a change, the control clear on a chip dismissal, and the clear on a reset; on a chip dismissal it also keeps the chip. |
chip-dismiss | Listens | Listened on the form for a chip dismissed inside the selected-chips region. Dispatches filter-change with the chip name/value and, unless a listener prevents it, unchecks or clears the matching control. |
Examples
Cleared
A <button type="reset"> inside the panel clears it. The script cancels the native reset and dispatches one cancelable filter-change carrying reason: 'reset'. Unless a listener calls preventDefault(), the script then clears the filter controls in place of the reset, because a reset would restore the selections the markup was authored with and leave the panel still filtered. Controls that carry no filter value are left alone - buttons keep their labels and a hidden field keeps the state the host put there - and a range returns to its authored value rather than blanking, since a slider has no empty state. The clear also removes every chip from the selected region.
Vertical single
One criterion whose chips are backed by radio inputs, stacked as a sidebar panel.
Horizontal single
The same single-choice criterion laid out as a bar above the results.
Vertical multiple
One criterion whose chips are backed by checkbox inputs, so several values can be active at once.
Horizontal multiple
The same multiple-choice criterion laid out as a bar above the results.
Vertical multiple with chips
Three criteria in a sidebar, with the current selection echoed as dismissible chips in a live region below the controls.
Horizontal multiple with chips
The same three criteria and selection summary laid out as a bar above the results.
Sticky
The sticky position value keeps the panel in view while the results beside it scroll, which is how a filter behaves in a listing sidebar. The offset it settles at comes from --filter-sticky-top. Scroll the canvas to see the panel hold its position against the moving stage; the value adds nothing on a page short enough to fit the viewport.
Accessibility
- WCAG 2.2 AA
- The
<form>has a descriptive heading or<legend> - Grouped controls sit inside a
<fieldset>with a<legend> - Selected filter chips use
aria-liveso updates are announced - Clear action is reversible or confirmed to avoid accidental loss
Dependencies
- collapsible - optional mobile collapse behavior
- chip - selected filter summary
- button - submit and clear actions
Related
- collection - typical parent for filter results
- select, checkbox, radio - common filter controls