pd-filter
See it live in the styled storefront › — the brand A–Z index above the product rail.
An index-filtered list (SPEC §5.5) — the behavior behind an A–Z brand index, a size-code filter, or any "press a button, list narrows" pattern. pd-filter never renders the index itself (you write plain <button>s) and never renders the list itself (you write a plain <ul>/<ol>/anything) — it only wires the two together: which buttons exist, which list items they match, and the hidden/aria-pressed/disabled bookkeeping that keeps both in sync. pd-filter-status is the optional third piece: an aria-live region that turns the filter's state into an announced sentence.
Anatomy
The canonical example — and the one this page's live demo builds on — is a brand index:
<!-- for: id of the LIST this filter narrows. Buttons live inside pd-filter
and target it via commandfor, exactly like any other pd-* component. -->
<pd-filter id="brand-filter" for="brand-list" match="starts-with">
<button commandfor="brand-filter" command="--pd-filter" value="a">A</button>
<button commandfor="brand-filter" command="--pd-filter" value="b">B</button>
<!-- … one button per letter … -->
<!-- comma list = any-of: one button can bucket several keys, e.g. digits. -->
<button commandfor="brand-filter" command="--pd-filter" value="0,1,2,3,4,5,6,7,8,9">0–9</button>
<!-- --pd-clear needs no [value] — it always resets to unfiltered. -->
<button commandfor="brand-filter" command="--pd-clear">All</button>
</pd-filter>
<!-- for here means something DIFFERENT: the FILTER's id, not a list id.
The initial text is captured verbatim as an i18n template — write it on
one line to avoid stray whitespace ending up in the live announcement. -->
<pd-filter-status for="brand-filter">Showing {count} of {total} brands</pd-filter-status>
<ul id="brand-list">
<!-- data-filter-value overrides the match key; without it, trimmed
textContent is used (so "Baxter Blue" below matches "b"). -->
<li data-filter-value="Alpha-H"><a href="/brands/alpha-h">Alpha-H</a></li>
<li><a href="/brands/baxter-blue">Baxter Blue</a></li>
</ul>Two things worth flagging up front because they're easy to trip on:
formeans two different things on the two elements.pd-filter[for]points at the list.pd-filter-status[for]points at the filter. They are never the same id.pd-filterrenders no landmark. If the index functions as page navigation (which a brand A–Z index usually does), wrap it yourself —<nav aria-label="Brand index">…</nav>— the same way the library's own a11y tests do it.
Items are [data-filter-item] descendants of the list if any exist, otherwise the list's direct element children — so a plain flat <ul><li>…</li></ul> works with zero extra markup, and a richer structure (e.g. items nested inside a wrapper <li>) opts in with data-filter-item on the actual matchable element.
Attributes
| Attribute | Type | Default | Notes |
|---|---|---|---|
for | string (id) | required | Id of the list container. Missing or unresolved → a dev warning and the filter stays inert (total is 0, every --pd-filter button renders disabled). |
match | starts-with | equals | includes | starts-with | Any other value (including a typo or omission) falls back to starts-with. Same mode is used for the active filter and for empty-group detection. |
value | string | null | absent | Reflects the active filter value. Setting it directly (el.setAttribute('value', 'b')) applies the filter exactly like invoking a button — it fires pd:filter too. |
toggle | "false" to opt out | on | When on (the default — any value other than the exact string "false"), re-pressing the currently-active button clears the filter instead of re-applying it. |
Properties & methods
| Member | Signature | Notes |
|---|---|---|
value | string | null (get/set) | The active filter value, or null when unfiltered. Setting it is equivalent to apply(value). |
count | number (get) | Currently visible item count. |
total | number (get) | Total item count in the resolved list. |
apply(value) | (value: string | null) => void | Applies a filter value programmatically — same pipeline as an invoker click; fires pd:filter. |
clear() | () => void | Shorthand for apply(null). |
refresh() | () => void | Re-resolves for and recomputes matches/empty-group state synchronously. The list already auto-refreshes on childList mutation (see below); call this yourself after swapping for to point elsewhere, or when you need the recompute to happen synchronously rather than waiting a microtask for the observer. |
Commands
| Command | Valid target | Effect |
|---|---|---|
--pd-filter | pd-filter | Applies the invoking button's value attribute as the filter (comma-separated = any-of). If toggle is enabled and the button is already active, clears instead. |
--pd-clear | pd-filter | Clears the filter (value → null), regardless of toggle. |
Events
| Event | Cancelable | When | detail |
|---|---|---|---|
pd:filter | no | After pd-filter applies or clears a value — from a button, from apply()/clear(), or from setting the value attribute directly. Does not fire on initial connect. | { value, count, total } |
pd:filter bubbles and is composed, so pd-filter-status (and any other listener) can sit on the document root and match by the filter's id rather than being wired per-instance. There's no pd:filtering/cancelable pre-event here (unlike the disclosure family's pd:open/pd:close) — filtering a list has nothing to veto.
Keyboard
pd-filter adds no custom key handling — every button stays natively tabbable, in DOM order, with no roving tabindex (unlike pd-nav's arrow-key widget). The one behavior worth calling out is what the component's own state does to the native tab order:
| Key | Context | Behavior |
|---|---|---|
Tab / Shift+Tab | anywhere in the index | Moves focus among filter buttons in DOM order. Buttons the component has marked disabled (empty groups — see below) are skipped entirely, per native disabled button semantics. |
Enter / Space | a filter button focused | Activates it (native), dispatching the command event pd-filter handles. |
One managed edge case: disabling the focused button would drop focus to <body> with no UA re-targeting. So when a list mutation empties the group the focused filter button points at, the component moves focus to the nearest enabled filter button (first after it, then before it), or failing that a --pd-clear button — keeping the focus order meaningful (WCAG 2.4.3).
pd-filter-status has no interactive surface — it's a passive role="status" region, never a tab stop.
Accessibility
The component manages, on every button whose command is --pd-filter:
aria-pressed="true"on the active button,"false"on every other--pd-filterbutton — toggle-button semantics for free, recomputed on everyapply()/clear()/attribute change.disabled+data-emptywhen the button's value set matches nothing currently in the list — see the dedicated section below for why this isdisabled, notaria-disabled.
A --pd-clear button is left alone. The aria-pressed/disabled/data-empty triad is only applied inside the --pd-filter branch of the recompute loop — an "All" button gets no managed ARIA at all. If you want it to visually/semantically reflect "currently active" (e.g. aria-pressed="true" when filter.value is null), you own that: listen for pd:filter and set it yourself.
On the list: matching items get hidden removed and data-state="shown"; non-matching items get hidden set and data-state="hidden" — applied synchronously, in the same tick as the recompute. This is a deliberate difference from the disclosure family: §3's animation-aware lifecycle is specific to pd-disclosure/pd-nav-panel/pd-drawer/ pd-drilldown-panel: those surfaces become inert before waiting, then panels receive hidden while a drawer uses native dialog.close(). An index filter is expected to feel instant, not staged — see the CSS recipe below for how to get a fade anyway, honestly, without fighting that synchronicity.
No aria-controls. Filter buttons target the filter via commandfor, not the list, and like every other component in this library, pd-filter never sets aria-controls (SPEC §2.3 — commandfor already provides the programmatic relationship, and AT support for aria-controls is inconsistent enough that this library doesn't rely on it anywhere). This is exactly why pd-filter-status matters: it's the mechanism that actually announces "the list changed," not aria-controls.
Why disabled, not aria-disabled
An empty letter (say "Q" when no brand starts with Q) gets the real disabled attribute, not aria-disabled="true". That's an intentional tradeoff, not an oversight:
disabledremoves the button from the tab sequence entirely — a keyboard or screen-reader user tabbing through the index never lands on a control that would do nothing if activated. For a dense A–Z index where several letters are routinely empty, that's a real efficiency win.- The cost is discoverability: an
aria-disabledbutton stays focusable and gets announced ("Q, dimmed" / "Q, unavailable"), which tells the user the full alphabet exists even when a letter is empty.disableddoesn't — a Tab-only user simply never encounters "Q" and has no way to know it was ever a possibility.
If your index needs the announced-but-inert behavior instead, pd-filter's own empty-group detection isn't the tool for it — you'd manage aria-disabled and the click no-op yourself rather than relying on the component's disabled output.
You must provide:
- Real
<button>elements as invokers, each with a visible, meaningful label — a bare "A" is standard practice for a compact letter index and is whataria-pressedannounces against ("A, button, pressed"), but addaria-label="Filter by A"if your index needs to be unambiguous out of context. - A landmark around the index if it functions as navigation (
<nav aria-label="…">— see Anatomy above);pd-filterrenders none itself. data-filter-valueon any list item whose match key shouldn't be its rawtextContent— e.g. an item containing an icon<svg>with a<title>, where the fallback textContent would include text you don't want folded into the match key.- A
pd-filter-statusif you want filtering announced at all. Without one, the list visibly changes with zero notification to screen reader users — SPEC §5.5 calls this out explicitly as a deliberate AA gap the component leaves to you to close, not a silent fallback. Treatpd-filter-statusas effectively required, not optional polish. - The
pd-filter-statustemplate itself, written as plain text with{count}/{total}/{value}placeholders (see i18n note below) — with no template captured, there's nothing to render onpd:filterat all.
pd-filter-status details
role="status"(an implicitaria-live="polite"region) is set on connect, always — even ifforfails to resolve. In that failure case you get a dev warning and the raw, never-substituted template text is left on screen (literallyShowing {count} of {total} brands), so a brokenforis visibly broken, not silently broken.- The template is captured from
textContentexactly as authored, including whitespace — keep the element's markup on one line, or the captured template (and every subsequent render) carries stray line breaks/indentation into the announced text. - It renders immediately on connect from the filter's current
value/count/totalgetters, before any interaction — so a screen reader landing on the page reads real numbers, never the raw placeholder text or a blank string. {value}substitutes to an empty string when the filter is cleared (value === null), not the word "null" or "all" — write your template with that in mind (e.g. put{value}somewhere it degrades gracefully to nothing, likeShowing {count} of {total} brands{value}→… brandswhen cleared, rather thanfor {value}→forwith a trailing space).- It only reacts to
pd:filterevents whose target id matches its ownfor— multiple independentpd-filter/pd-filter-statuspairs on one page don't cross-talk.
The placeholders above are shown here inside backticks/fences deliberately — {count} etc. are single curly braces (Vue's template compiler in VitePress only treats a matching pair of adjacent double curly braces as interpolation), so they're safe as literal element text in the live demo too, as long as no two placeholders ever sit adjacent enough to form that pair.
Styling — vanilla CSS
/* A–Z index: a uniform grid of square letter buttons — grid, not flex, since
every cell is the same intrinsic size and wraps to fill the row. */
pd-filter {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(2.25rem, 1fr));
gap: 0.375rem;
}
pd-filter button {
aspect-ratio: 1;
border: 1px solid currentColor;
border-radius: 4px;
cursor: pointer;
}
/* aria-pressed IS the active-letter indicator — no separate class needed. */
pd-filter button[aria-pressed='true'] {
background: currentColor;
color: Canvas; /* system-color keyword: readable against currentColor in light + dark */
}
/* Empty letters: real `disabled` (see docs above for why). Style them
in-place rather than hiding them, so the A–Z shape stays legible even
when a bucket is empty. */
pd-filter button:disabled {
opacity: 0.35;
cursor: not-allowed;
}
/*
* Filtered-out list items: pd-filter toggles `hidden` SYNCHRONOUSLY (no
* afterAnimations grace period — that's specific to animated panel surfaces,
* see the Accessibility section above). A plain opacity transition can't
* play on exit because `hidden` removes the box in the very same tick.
* `transition-behavior: allow-discrete` defers the discrete `display: none`
* jump until the opacity transition finishes — the standard, spec-provided
* way to animate *to* display:none. It needs `display: none` to NOT be
* `!important` on this selector (unlike a blanket base.css reset) or the
* cascade wins before the transition gets a chance to run.
*/
#brand-list > li {
transition: opacity 160ms ease, display 160ms ease allow-discrete;
}
#brand-list > li[hidden] {
display: none;
}
#brand-list > li[data-state='hidden'] {
opacity: 0;
}
@media (prefers-reduced-motion: reduce) {
#brand-list > li {
transition: none;
}
}Styling — Tailwind
<pd-filter class="grid grid-cols-[repeat(auto-fill,minmax(2.25rem,1fr))] gap-1.5">
<button
commandfor="brand-filter"
command="--pd-filter"
value="a"
class="aspect-square rounded border border-current
aria-pressed:bg-current aria-pressed:text-[Canvas]
disabled:opacity-35 disabled:cursor-not-allowed"
>
A
</button>
<!-- … -->
<button
commandfor="brand-filter"
command="--pd-clear"
class="col-span-2 rounded border border-current"
>
All
</button>
</pd-filter>
<ul id="brand-list" class="grid gap-2">
<li
data-filter-value="Alpha-H"
class="transition-[opacity,display] duration-150 [transition-behavior:allow-discrete]
data-[state=hidden]:opacity-0 motion-reduce:transition-none"
>
<a href="/brands/alpha-h">Alpha-H</a>
</li>
</ul>- Tailwind's
hidden/preflight[hidden]rule is plaindisplay: none(not!important), so unlike a hand-rolled reset it plays nicely withallow-discreteout of the box — thedata-[state=hidden]:opacity-0variant is all you add. aria-pressed:anddisabled:are Tailwind's built-in ARIA/state variants — no arbitrary selectors needed for the button states.motion-reduce:transition-noneis Tailwind'sprefers-reduced-motion: reduceguard.
Live demo
An A–Z-style index over a small brand list, with a pd-filter-status live region and one deliberately-empty letter ("E") to show the disabled/data-empty state without needing you to click anything.