Skip to content

Filter chips

Toggle chips that filter a list by up to six values, kept in the address with a live count.

<div class="cap-chips" data-cap="chips" data-param="status" role="group" aria-labelledby="chips-live-l" id="chips-live">
  <span class="cap-chips-label" id="chips-live-l">Status</span>
  <button type="button" class="cap-chip" aria-pressed="false" data-value="blocked">Blocked</button>
  <button type="button" class="cap-chip" aria-pressed="false" data-value="running">Running</button>
  <button type="button" class="cap-chip" aria-pressed="false" data-value="queued">Queued</button>
  <button type="button" class="cap-chip" aria-pressed="false" data-value="done">Done</button>
  <button type="button" class="cap-link-btn" data-cap-part="clear" hidden>Clear</button>
  <span class="cap-chips-count" role="status">14 jobs</span>
</div>
<div id="live-empty" hidden>
  <p id="live-empty-text">No jobs match "Done".</p>
  <button type="button" class="cap-btn" id="live-empty-clear">Clear filter</button>
</div>

Installation

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

enhance();

Usage

<div class="cap-chips" data-cap="chips" data-param="status" role="group" aria-labelledby="status-l">
  <span class="cap-chips-label" id="status-l">Status</span>
  <button type="button" class="cap-chip" aria-pressed="false" data-value="blocked">Blocked</button>
  <button type="button" class="cap-chip" aria-pressed="false" data-value="running">Running</button>
  <button type="button" class="cap-link-btn" data-cap-part="clear" hidden>Clear</button>
  <span class="cap-chips-count" role="status">14 jobs</span>
</div>
import { enhance, pressedValues, setCount } from "capsomer/behavior/chips";
enhance();
group.addEventListener("cap:filter-change", (e) => {
  const shown = jobs.filter((j) => e.detail.values.length === 0 || e.detail.values.includes(j.status));
  setCount(group, `${shown.length} of ${jobs.length} jobs`);
});
<fieldset class="cap-chips">
  <legend class="cap-chips-label">Type</legend>
  <label class="cap-chip"><input class="cap-chip-input" type="checkbox" name="type" value="grant" checked> Grants <span class="cap-chip-count">43</span></label>
  <label class="cap-chip"><input class="cap-chip-input" type="checkbox" name="type" value="talk"> Invited talks <span class="cap-chip-count">14</span></label>
</fieldset>
<FilterChips label="Status" options={statuses} value={status} onChange={setStatus} count={`${shown.length} of ${jobs.length} jobs`} />

Examples

Some pressed, with the count

<div class="cap-chips" role="group" aria-labelledby="chips-some-l" id="chips-some">
  <span class="cap-chips-label" id="chips-some-l">Status</span>
  <button type="button" class="cap-chip" aria-pressed="true" data-value="blocked" id="chip-pressed">Blocked</button>
  <button type="button" class="cap-chip" aria-pressed="true" data-value="running">Running</button>
  <button type="button" class="cap-chip" aria-pressed="false" data-value="queued" id="chip-unpressed">Queued</button>
  <button type="button" class="cap-chip" aria-pressed="false" data-value="done">Done</button>
  <button type="button" class="cap-link-btn" id="chips-some-clear">Clear</button>
  <span class="cap-chips-count" role="status" id="chips-some-count">5 of 14 jobs</span>
</div>
<nav aria-label="Tags" id="chips-links">
  <ul class="cap-chips">
    <li><a class="cap-chip" href="?">Any tag</a></li>
    <li><a class="cap-chip" href="?tag=release" aria-current="true" id="chip-link-current">release <span class="cap-chip-count">4</span></a></li>
    <li><a class="cap-chip" href="?tag=capsid" id="chip-link">capsid <span class="cap-chip-count">7</span></a></li>
  </ul>
</nav>

Checkbox chips: a filter in a form, with no script

<form id="chips-boxes-form" action="#">
  <fieldset class="cap-chips" id="chips-boxes">
    <legend class="cap-chips-label">Type</legend>
    <label class="cap-chip" id="chip-box-checked"><input class="cap-chip-input" type="checkbox" name="type" value="grant" checked> Grants <span class="cap-chip-count">43</span></label>
    <label class="cap-chip" id="chip-box"><input class="cap-chip-input" type="checkbox" name="type" value="talk"> Invited talks <span class="cap-chip-count">14</span></label>
    <label class="cap-chip"><input class="cap-chip-input" type="checkbox" name="type" value="course" disabled> Courses taught <span class="cap-chip-count">0</span></label>
  </fieldset>
</form>

Keyboard focus and hover

<p class="cap-muted">Tab to a chip to see focus. The second chip is shown hovered.</p>
<div class="cap-chips" role="group" aria-labelledby="chips-focus-l">
  <span class="cap-chips-label" id="chips-focus-l">Kind</span>
  <button type="button" class="cap-chip" aria-pressed="false">Reply</button>
  <button type="button" class="cap-chip" aria-pressed="false" id="chip-hover">Link</button>
  <button type="button" class="cap-chip" aria-pressed="false">Like</button>
  <span class="cap-chips-count" role="status">23 mentions</span>
</div>

An empty result

<div class="cap-chips" role="group" aria-labelledby="chips-empty-l">
  <span class="cap-chips-label" id="chips-empty-l">Status</span>
  <button type="button" class="cap-chip" aria-pressed="true">Blocked</button>
  <button type="button" class="cap-chip" aria-pressed="false">Running</button>
  <button type="button" class="cap-chip" aria-pressed="false">Queued</button>
  <button type="button" class="cap-link-btn">Clear</button>
  <span class="cap-chips-count" role="status">0 of 14 jobs</span>
</div>
<div>
  <p id="empty-text">No jobs match "Blocked". 14 jobs are hidden by this filter.</p>
  <button type="button" class="cap-btn">Clear filter</button>
</div>
<p class="cap-muted">In an app this is the empty component's no-match kind, which names the filter and offers Clear.</p>

Pressed and hovered, small and large, disabled, with a count and an icon

<div class="cap-chips" role="group" aria-labelledby="chips-more-l" id="chips-more">
  <span class="cap-chips-label" id="chips-more-l">States</span>
  <button type="button" class="cap-chip" aria-pressed="true" id="chip-pressed-hover">Blocked</button>
  <button type="button" class="cap-chip" aria-pressed="false" data-size="sm" id="chip-sm">Small</button>
  <button type="button" class="cap-chip" aria-pressed="false" data-size="lg" id="chip-lg">Large</button>
  <button type="button" class="cap-chip" aria-pressed="false" aria-disabled="true" id="chip-disabled">Archived</button>
  <button type="button" class="cap-chip" aria-pressed="false" id="chip-count">Failed <span class="cap-chip-count">3</span></button>
  <button type="button" class="cap-chip" aria-pressed="true" id="chip-icon"><svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><circle cx="8" cy="8" r="5" fill="currentColor" /></svg>Live</button>
</div>

Comfortable density

<div class="cap-chips" role="group" aria-label="Kind" data-density="comfortable" id="chips-comf">
  <button type="button" class="cap-chip" aria-pressed="true">Reply</button>
  <button type="button" class="cap-chip" aria-pressed="false">Link</button>
</div>

Solid, one of a few with All

<div class="cap-chips" data-variant="solid" role="group" aria-label="Filter features by product" id="chips-solid">
  <button type="button" class="cap-chip" aria-pressed="true" data-value="All">All</button>
  <button type="button" class="cap-chip" aria-pressed="false" data-value="Reports">Reports</button>
  <button type="button" class="cap-chip" aria-pressed="false" data-value="Invoices">Invoices</button>
</div>

API reference

FilterChips

PropTypeRequiredDoes
labelReactNodeYesThe visible label of the group: "Status".
optionsArray<ChipOption<V>>YesUp to six.
valueV[]YesControlled: the pressed values, in any order.
onChange(value: V[]) => voidYesCalled with the pressed values in the options' order. Keep them in the address (writeParam from "capsomer/behavior/chips" makes ?status=blocked,running).
countReactNodeYesWhat the filter leaves, in words: "3 of 14 jobs". Announced politely as it changes.
size"sm" | "default" | "lg"

LinkChips

PropTypeRequiredDoes
labelstringYes
showLabelbooleanShow the label before the chips (as FilterChips does); it then names the nav.
chipsreadonly LinkChip[]Yes
size"sm" | "default" | "lg"
renderLink(props: { href: string; className: string; "aria-current"?: "true"; "data-size"?: string; children: ReactNode; }) => ReactNode

CheckChips

PropTypeRequiredDoes
legendReactNodeYes
namestringYes
optionsReadonlyArray<{ value: string; label: ReactNode; count?: number; disabled?: boolean }>Yes
checkedreadonly string[]YesThe values checked now (from the address).
size"sm" | "default" | "lg"

Functions

FunctionSignatureDoes
valueOf(chip: HTMLElement): string
pressedValues(group: Element): string[]
syncClear(group: Element): voidShows Clear while any chip is pressed.
ensureChips(group: Element, values: string[]): voidA value from the address that no chip carries still shows, pressed, after the last chip. Without it a filter in a shared link would narrow the list with nothing on the page to say so or to release (the Portal's NsChips does the same with a namespace its list does not carry).
setPressed(group: Element, values: string[]): void
readParam(search: string, param: string): string[] | nullThe values in an address's search string, or null when the parameter is absent.
writeParam(href: string, param: string, values: string[]): stringThe address with the parameter set to the values, comma-separated and readable (?status=blocked,running), or removed when there are none. Values must not hold commas.
setCount(group: Element, text: string): voidWrites the result count into the group's live region: "3 of 14 jobs".
toggle(group: HTMLElement, chip: HTMLElement): voidPresses or releases one chip, as a click does.
clearAll(group: HTMLElement): voidReleases every chip, as Clear does. Clear hides itself, so focus goes to the first chip rather than being lost. An empty result's own Clear button calls this too.
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="chips"] under root that is not attached yet. With data-param, the group reads its starting state from the address and writes it back. Returns a function that detaches them all.

Parts and data attributes

ClassIs
.cap-chip-countits own class
.cap-chip-inputits own class
.cap-chipsthe root
.cap-chips-counta part
.cap-chips-labela part
AttributeValues
data-sizelg sm
data-variantsolid
StateRead from
:checkedthe platform
:disabledthe platform
:focus-visiblethe platform
:hoverthe platform
[aria-current="false"]an attribute
[aria-current]an attribute
[aria-disabled="true"]an attribute
[aria-pressed="true"]an attribute

Accessibility

KeyDoes
TabMoves through the chips, then Clear while any is pressed
Enter or SpacePresses or releases a chip; the count and the address follow
Enter on ClearReleases every chip and moves focus to the first
Arrow keysMove focus to the next or previous chip without pressing it (wraps)
Home or EndMove focus to the first or last chip
  • Toggle buttons, not checkboxes: each is a button whose pressed state is read out.
  • Each chip is at least var(--target) tall; 44 px on a touch screen.
  • Forced colors: a pressed chip is drawn in Highlight.