Skip to main content

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​

SlotRequiredDescription
contentYesHTML string for the inner contents of the filter panel, including groups, selected chips, and actions.

Props​

PropTypeDefaultDescription
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.horizontalOrientation-Children flow along the horizontal axis.
.verticalOrientationYesChildren flow along the vertical axis.
.stickyPosition-Pins the component to a viewport edge while scrolling.
.flatElevationYesNo elevation.
.raisedElevation-Slight elevation.

Attributes​

AttributeSet byRequiredDescription
data-filterConsumerYesMarks the filter form root; the change-announcement and chip-driven-uncheck behaviors bind to it.
data-filter-selectedConsumer-Marks the selected-chips summary region where the behavior materializes and removes chips.
data-chipConsumer-Owned by the chip component; the filter sets it on chips it generates and matches it to recognize chips in the selected region.
data-closeConsumer-Set by the filter on the injected dismiss button inside a generated chip so the close utility wires up its dismiss interaction.

Events​

EventDirectionDescription
filter-changeEmitsFired 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-dismissListensListened 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-live so 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