Skip to content

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:

html
<!-- 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:

  • for means 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-filter renders 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 ​

AttributeTypeDefaultNotes
forstring (id)requiredId of the list container. Missing or unresolved → a dev warning and the filter stays inert (total is 0, every --pd-filter button renders disabled).
matchstarts-with | equals | includesstarts-withAny 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.
valuestring | nullabsentReflects 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 outonWhen 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 ​

MemberSignatureNotes
valuestring | null (get/set)The active filter value, or null when unfiltered. Setting it is equivalent to apply(value).
countnumber (get)Currently visible item count.
totalnumber (get)Total item count in the resolved list.
apply(value)(value: string | null) => voidApplies a filter value programmatically — same pipeline as an invoker click; fires pd:filter.
clear()() => voidShorthand for apply(null).
refresh()() => voidRe-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 ​

CommandValid targetEffect
--pd-filterpd-filterApplies 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-clearpd-filterClears the filter (value → null), regardless of toggle.

Events ​

EventCancelableWhendetail
pd:filternoAfter 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:

KeyContextBehavior
Tab / Shift+Tabanywhere in the indexMoves 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 / Spacea filter button focusedActivates 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-filter button — toggle-button semantics for free, recomputed on every apply()/clear()/attribute change.
  • disabled + data-empty when the button's value set matches nothing currently in the list — see the dedicated section below for why this is disabled, not aria-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:

  • disabled removes 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-disabled button stays focusable and gets announced ("Q, dimmed" / "Q, unavailable"), which tells the user the full alphabet exists even when a letter is empty. disabled doesn'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 what aria-pressed announces against ("A, button, pressed"), but add aria-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-filter renders none itself.
  • data-filter-value on any list item whose match key shouldn't be its raw textContent — 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-status if 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. Treat pd-filter-status as effectively required, not optional polish.
  • The pd-filter-status template itself, written as plain text with {count}/{total}/ {value} placeholders (see i18n note below) — with no template captured, there's nothing to render on pd:filter at all.

pd-filter-status details ​

  • role="status" (an implicit aria-live="polite" region) is set on connect, always — even if for fails to resolve. In that failure case you get a dev warning and the raw, never-substituted template text is left on screen (literally Showing {count} of {total} brands), so a broken for is visibly broken, not silently broken.
  • The template is captured from textContent exactly 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/total getters, 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, like Showing {count} of {total} brands{value} → … brands when cleared, rather than for {value} → for with a trailing space).
  • It only reacts to pd:filter events whose target id matches its own for — multiple independent pd-filter/pd-filter-status pairs 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 ​

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 ​

html
<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 plain display: none (not !important), so unlike a hand-rolled reset it plays nicely with allow-discrete out of the box — the data-[state=hidden]:opacity-0 variant is all you add.
  • aria-pressed: and disabled: are Tailwind's built-in ARIA/state variants — no arbitrary selectors needed for the button states.
  • motion-reduce:transition-none is Tailwind's prefers-reduced-motion: reduce guard.

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.