Filter Bar - Canvas Design System

When to Use

Use when: A listing needs GET-based search or filtering, with or without filters — exercise lists, workshop catalogues, saved-plan tables, a search box above "My workshops". It standardises controls that were previously rebuilt per page. Its "Clear all" link beside the chips is the one clear control DESIGN.md 11.6 allows: it loads the unfiltered list, and Back undoes it.

Don't use when: The search field belongs to a form about something else, or sits in the site header rather than above a list — use Input with type: 'search'. For client-side switching between a few fixed sets, Tabs is lighter.

Variants

Search and filters

The common case. Filters render through Select internally, so they inherit its styling and focus treatment.

<?= ws_filter_bar([
    ['name' => 'category_id', 'label' => 'Category',
     'options' => [1 => 'Design Sprints', 2 => 'Icebreakers'], 'value' => 1],
    ['name' => 'duration', 'label' => 'Duration',
     'options' => ['short' => 'Under 30 min', 'long' => 'Over 1 hour']],
], [
    'search' => ['placeholder' => 'Search activities…'],
]) ?>

Search only

The search box above a list, with no filters: pass an empty filters array. The submit button reads "Search" rather than "Filter", and showSearchLabel puts the field's name above it as a visible label, which a placeholder is not.

<?= ws_filter_bar([], [
    'search' => ['placeholder' => 'e.g. retrospective', 'value' => $q, 'name' => 'q'],
    'searchLabel' => 'Search your workshops by name',
    'showSearchLabel' => true,
]) ?>

With active chips

Chips summarise what's applied, with a "Clear all" alongside. Each remove button names its filter, here "Remove Design Sprints filter".

<?= ws_filter_bar($filters, [
    'activeChips' => [['label' => 'Design Sprints', 'name' => 'category_id', 'value' => 1]],
]) ?>

States

State	Behavior
Default	A GET form. Submitting puts search and filter values in the query string, so filtered views are linkable and survive a reload.
Filter selected	Pass the filter's current `value` so the dropdown reflects the query string on redisplay.
Focus	Search and selects use the shared `--focus-ring-width` / `--focus-ring-offset` geometry.
Chips shown	Rendered whenever `activeChips` is non-empty, with a "Clear all" link: the one clear control DESIGN.md 11.6 allows, because it loads the unfiltered list and Back undoes it. Building the chip array is yours — the component doesn't derive it from the filters.
Chip removal	Handled by `wsFilterBarRemove()` in `components.js`: drops that one parameter, resets `page`, keeps the rest of the query string and the hash, then reloads.
Empty results	Not handled here. Pair the bar with Empty State below the grid.

Real-World Usage

The exercises listing. Chips are derived from the query string, and the missing remove function is supplied locally — it drops one parameter and reloads, which is all it needs to do.

<?php
$chips = [];
if (!empty($_GET['category_id'])) {
    $chips[] = ['label' => $categoryNames[$_GET['category_id']],
                'name'  => 'category_id',
                'value' => $_GET['category_id']];
}
if (!empty($_GET['duration'])) {
    $chips[] = ['label' => $durationLabels[$_GET['duration']],
                'name'  => 'duration',
                'value' => $_GET['duration']];
}
?>
<?= ws_filter_bar($filters, [
    'search'      => ['placeholder' => 'Search activities…', 'value' => $_GET['q'] ?? ''],
    'activeChips' => $chips,
]) ?>

<!-- Chip removal needs no wiring — wsFilterBarRemove() ships in components.js -->

<?php if (!$results): ?>
    <?= ws_empty_state('Nothing matches those filters', [
        'icon' => 'filter_alt_off', 'action' => 'Clear filters', 'actionHref' => '?',
    ]) ?>
<?php endif; ?>

Options

Bar options

Option	Type	Default	Purpose
`$filters`	array	`[]`	Positional. Dropdown configs; may be empty for search-only.
`search`	array	`null`	`['placeholder' => …, 'value' => …, 'name' => 'q']`. Omit for filters only.
`searchLabel`	string	the placeholder	The search input's accessible name (its `aria-label`). Defaults to the placeholder less any trailing ellipsis, or "Search". Set it when the placeholder is an example rather than a description.
`showSearchLabel`	bool	`false`	Shows `searchLabel` as a visible `<label>` above the field; the row then lines up on the inputs.
`submitLabel`	string	`'Search'` or `'Filter'`	The submit button's text: "Search" with no filters, "Filter" with them.
`keep`	array	`[]`	Query-string names the search and "Clear all" carry through, as hidden fields: inside `/app/`, `['view', 'step']`, or a search sends the person back to Home. Inside a tab panel of a `ws_tabs` with a `param`, the panel's own tab is carried too, without listing it.
`activeChips`	array	`[]`	`[['label' => …, 'name' => …, 'value' => …]]`. You build this from the query string.
`color`	string	`'learn'`	`learn` \| `plan` \| `facilitate` \| `reflect`. `learn`, the default, has no rule of its own: it is the base look, and since the Red Unification the other three render the same.
`class`	string	`''`	Additional CSS classes on the container
`attrs`	array	`[]`	Extra HTML attributes on the container

Filter options

Option	Type	Default	Purpose
`name`	string	`''`	Query-string parameter name
`label`	string	`''`	The select's accessible name (its `aria-label`) and the text of its empty "any" option
`options`	array	`[]`	Flat `value => label` pairs, as `ws_select()` takes
`value`	string	`''`	Currently selected value

Accessibility

Concern	Behavior
Semantics	A real GET `<form>` with native inputs, so filtered views are linkable and the back button behaves.
Names	Every control is named without changing the look. Each select's `aria-label` is its filter `label`; the search input's is `searchLabel`, or the placeholder. They are `aria-label` rather than a hidden `<label for>` because a select's id defaults to its field name, and two bars with the same filter on one page would point both labels at the first select. A placeholder alone is not a name: it disappears as soon as someone types.
Search landmark	With a search field the form is `role="search"`, named like the field, so a screen reader can jump straight to it. Two bars on one page need different `searchLabel`s, or the landmark list shows two entries with the same name.
Keyboard	Native throughout: `Tab` across search and selects, `Enter` in the search field submits.
Chip remove buttons	Each names its filter, `aria-label="Remove Design Sprints filter"`, so a row of chips does not announce the same words for every button.
Announcing results	Because submission reloads the page, the new result count is announced as part of the new page. If you ever move to async filtering, add a live region for the count.
Focus after reload	A full reload returns focus to the top of the document, so a keyboard user must tab back to the controls. Consider focusing the results heading on load when filters are applied.
Search icon	Decorative and `aria-hidden`, so the icon's ligature text is not read. The field's own name carries the meaning.

Tokens

Token	Used for
`--bg-surface`	Bar and search-field background
`--color-border`	Bar and field borders
`--color-ink` / `--color-ink-muted`	Field text and the chips label
`--brand` / `--phase-facilitate` / `--phase-reflect`, with `--phase-plan-light` / `--phase-facilitate-light` / `--phase-reflect-light`	Colour-key accents (all red since Red Unification)
`--focus-ring-width` / `--focus-ring-offset`	Focus geometry on search and selects
`--radius-lg`	Bar and field corners
`--space-2` / `--space-3` / `--space-4` / `--space-6`	Control spacing and the chips row
`--text-caption` / `--text-ui`	Chip and control type scale
`--font-body` / `--font-medium`	Face and weight
`--transition-fast`	Hover and focus transitions

CSS Classes

Class	Purpose
`.ws-filter-bar`	The form container
`.ws-filter-bar--plan / --facilitate / --reflect`	Colour keys. `--learn`, the default, is emitted by the template but has no rule: it is the base look.
`.ws-filter-bar__controls`	Search and selects row
`.ws-filter-bar__search` / `__search-input` / `__search-icon`	Search field and its icon
`.ws-filter-bar__selects`	Dropdown group
`.ws-filter-bar__submit`	Submit button
`.ws-filter-bar__chips` / `__chips-label`	Active-chip row and its label
`.ws-filter-bar__clear-all`	"Clear all" link
`.ws-filter-chip`	An individual chip. Carries `data-filter-name` and `data-filter-value`.
`.ws-filter-chip__clear`	Chip remove button; calls `wsFilterBarRemove()`

Files

File	Purpose
`includes/components/helpers.php`	`ws_filter_bar()` helper function
`includes/components/filter-bar.php`	Template — form, search, chips. Renders `ws_select()` for each filter.
`includes/components/components.css`	Styles (`.ws-filter-bar` and `.ws-filter-chip` rules)
`includes/components/components.js`	`wsFilterBarRemove()` — chip removal