Skip to content

Getting started ​

pd-components is a set of unstyled custom elements that provide behavior and accessibility — open/close state, focus management, ARIA syncing, keyboard maps — for common storefront navigation patterns. They render light DOM (no Shadow DOM), so any CSS you already have reaches every part of every component. You bring the markup and every pixel of styling; see Styling once you're wired up.

Install ​

Install pd-components from the root of a theme repository with create-theme. pd-components is not an npm package, so do not run npm install @prosperdigital/pd-components.

sh
# Browse the component-set catalog
bun x @prosper-digital-au/create-theme components

# Scaffolded Vite theme: install only the sets your theme uses
bun x @prosper-digital-au/create-theme components add mega-menu mobile-menu

# Plain theme without a build pipeline: install the self-contained bundle
bun x @prosper-digital-au/create-theme components add mega-menu --bundle-only

The default vendor mode copies the selected source into frontend/vendor/pd-components/, generates the registration bootstrap, and adds the required JS and CSS imports to the theme entrypoints. Vite tree-shakes every component set you did not ask for; the vendored files are committed, so CI does not need registry access.

--bundle-only is for plain themes. It writes the self-contained bundle and stylesheet to assets/, creates snippets/pd-components.liquid, and renders that snippet before </head> in layout/theme.liquid. The bundle has the Invoker Commands polyfill inlined and registers every pd-* element automatically.

create-theme resolves the component source from node_modules, a sibling ../pd-components checkout, or a temporary clone. You can explicitly choose a checkout or git URL with --from; see the create-theme components command reference for the complete options.

Manual bundle fallback ​

For a project that does not use create-theme, build from a checkout of this repository (or use the equivalent file supplied with a release):

sh
npm ci             # this installs only the repository's build dependencies
npm run build

Copy dist/pd-components.js into your project's assets. It is a single-file ESM bundle with the Invoker Commands polyfill inlined and every pd-* element already registered. Load it once as a module:

html
<script type="module" src="/assets/pd-components.js"></script>

That's the entire JavaScript integration — no other <script> tags, import maps, package installation, or initialization call. (The Shopify guide covers vendoring this file into a theme's assets/ directory and wiring linklists into the flat markup the components expect.)

The Invoker Commands mental model ​

Every interaction an author wires up is expressed with the platform's Invoker Commands API: a <button> declares what it does with command, and which element it acts on with commandfor (a target id). No addEventListener required for the common cases:

html
<button commandfor="shipping" command="--pd-toggle">Shipping &amp; returns</button>
<pd-disclosure id="shipping"><p>Ships in 3–5 business days.</p></pd-disclosure>

Components never invent their own click handling for this — they listen for the standard command event on themselves and act on event.command. That means:

  • Buttons stay real <button> elements (focusable, Enter/Space activation, form-safe outside a <form method=dialog>) for free.
  • The association is programmatic (commandfor) rather than DOM-nesting, so triggers and panels can live anywhere in the markup relative to each other — a requirement for mega menus where the trigger is a top-level link/button and the panel is a full-width grid row.
  • The same markup works whether the browser has native support or needs the polyfill.

Command vocabulary ​

CommandValid target(s)Effect
--pd-togglepd-disclosure, pd-nav-panel, drawer's <dialog>Toggle open/closed
--pd-opensameOpen (no-op if already open)
--pd-closesameClose (no-op if already closed)
show-modal (native)drawer's <dialog>Intercepted → routed through the drawer's cancelable, animated open path (never the browser's un-animated default)
close (native)drawer's <dialog>Intercepted → routed through the drawer's cancelable, animated close path
--pd-drillpd-drilldown-panelPush current panel, activate the target
--pd-backpd-drilldown or a pd-drilldown-panelPop the stack
--pd-filterpd-filterApply a filter; the button's value attribute is the filter value
--pd-clearpd-filterClear the active filter
--pd-prev / --pd-nextpd-dynamic-grid's scrollerPage the carousel back / forward (RTL-aware, cumulative, clamped)
--pd-gotopd-dynamic-grid's scrollerScroll to the item at the button's value index (slide dots)

The --pd-* names follow the platform's convention for custom (non-built-in) commands — a leading double dash, guaranteed never to collide with a future native command. Every component page's Commands table documents the full detail for that element.

Polyfill: applied only when needed ​

src/define.ts feature-detects before importing the polyfill at all:

js
const needsPolyfill =
  typeof globalThis.CommandEvent === 'undefined' ||
  !('commandForElement' in HTMLButtonElement.prototype)

if (needsPolyfill) await import('invokers-polyfill')

On a browser that already ships Invoker Commands natively, the polyfill code is never evaluated. This check runs once, when the standalone bundle registers the elements.

The state contract ​

Every panel-like component exposes its state through plain HTML attributes, never through JS-set inline styles or classes you have to intercept. pd-disclosure and pd-nav-panel carry the full open/data-state/inert/hidden contract below. pd-drawer mirrors state and inert to its native <dialog>, but finishes closing with dialog.close() instead of hidden. pd-drilldown-panel carries data-state/inert/hidden, driven by its parent pd-drilldown (no open attribute or show()/hide() of its own). pd-header is intentionally different: it only uses data-state and remains reachable so focus can reveal a visually translated header.

Attribute / propertyWhat it meansWho sets it
open (boolean attribute, reflected open property)Logical state — is this panel supposed to be visible. Authors may server-render it.Author or component (via show()/hide()/toggle())
data-statePresentation state for CSS/Tailwind hooks — "open"/"closed" (disclosure-likes), "active"/"inactive" (drilldown panels), "visible"/"hidden" (header)Component only
inert (native boolean attribute)Interaction state — added synchronously on closing/inactive panel-like surfaces; component-owned inertness is removed before open/activationComponent, preserving author-supplied inertness
hidden (native boolean attribute)Visibility — removed from layout after exit animations; used by disclosure/nav/drilldown panels, while drawers use native dialog.close()Component only
aria-expanded on every button[commandfor] targeting the panelAssistive-tech state for the triggerComponent only

The close sequence is where most of the subtlety lives. The shared prefix is synchronous: data-state flips to "closed"/"inactive" so exit CSS starts, then component-owned inert lands on the surface so its still-rendered descendants immediately leave the accessibility tree and Tab order. The component then awaits every running CSS animation/transition on the surface (getAnimations({ subtree: true })). Disclosure/nav panels finish with hidden + pd:closed; drawers finish with dialog.close(), focus restoration, and pd:closed; drilldown panels finish with hidden and no close event.

Opening/activation is not deferred: pending close work is invalidated, only component-owned inertness is removed, and the surface is revealed before focus may enter it. Author-supplied inert is never removed. See the animation cookbook for the CSS recipes this enables.

Events, and why they're cancelable ​

Two of the four lifecycle events are cancelable, letting you veto a state change before it commits:

EventCancelableFires
pd:openyesbefore opening
pd:closeyesbefore closing
pd:openednoafter open/data-state are applied
pd:closednoafter exit animations settle and a disclosure/nav panel is hidden or a drawer dialog is natively closed
js
disclosure.addEventListener('pd:open', (e) => {
  if (formIsDirty()) e.preventDefault() // stays closed; open never happens
})

detail.reason tells you why the state changed — 'command' | 'hover' | 'focus' | 'keyboard' | 'outside' | 'escape' | 'focusout' | 'api' | 'attribute' — which matters for things like "only auto-focus the panel's first field when a human opened it via keyboard, not on hover." One consequence worth internalizing: directly mutating the open attribute bypasses cancelation (reason: 'attribute'). The attribute is always the source of truth — show()/hide() are a convenience path that can be vetoed, but el.open = true (or setAttribute('open', '')) always wins. All events bubble and are composed, so a listener on document catches everything.

Each component page documents its full event table (including pd-filter's pd:filter, pd-drilldown's pd:navigate, and pd-header's pd:show/pd:hide, none of which are part of the open/close pipeline above).

styles/base.css and why [hidden] needs !important ​

The repository includes an optional, tiny stylesheet with zero visual design — no colors, no spacing, no brand opinions. Copy styles/base.css into your site's assets and link it:

html
<link rel="stylesheet" href="/assets/pd-components-base.css">

It contains four functional guards:

  1. [hidden] { display: none !important; } — see below, this is the one that actually matters.
  2. display: block defaults for every pd-* element (custom elements are display: inline by default, same as a <span>, which silently breaks any layout that assumes a block box).
  3. A UA-chrome reset on pd-drawer dialog (margin/padding/border/background) so the native <dialog> starts from zero instead of the browser's default panel styling.
  4. A prefers-reduced-motion guard that zeroes transition/animation on the library's elements — a safety net; component pages' recipes also scope their own reduced-motion guards.

Why the !important matters: components close panels by toggling the native hidden attribute (§3 of SPEC.md), not a class. The HTML spec gives [hidden] a UA-stylesheet rule with normal specificity (display: none), which is trivially outranked by any author rule targeting the same element with equal-or-higher specificity — most commonly a utility class applied directly to a pd-* element for layout, e.g. <pd-nav-panel class="grid">. Without a stronger [hidden] rule, that .grid { display: grid } declaration can win the cascade and leave a "closed" panel fully laid out and painted. Managed inert still protects keyboard and assistive-technology users, but it cannot remove that visual/layout leak or block every possible author-script interaction. !important makes hidden win unconditionally, regardless of what utility classes you stack on top.

One more mechanism works alongside the specificity story: the whole file sits in a cascade layer, @layer pd-base, which makes load order irrelevant. For normal declarations, layered rules always lose to your unlayered theme CSS — so guards 2–4 can never beat your styles even when a bundler appends base.css after them. For !important declarations, layer priority inverts, so being layered makes the [hidden] guard stronger, not weaker.

Tailwind v4's own preflight already ships the equivalent rule, so Tailwind-based projects typically don't need base.css for this specific guard — but they still benefit from guards 2–4, and any vanilla-CSS or hand-rolled-reset project needs guard 1 explicitly (either via base.css or by replicating the one-line rule).

Next steps ​

  • Styling — vanilla CSS and Tailwind recipes for every state hook above, plus the grid-first mega-menu layout and animation cookbook.
  • Accessibility — the ARIA and focus contract in full.
  • Component pages (sidebar) — anatomy, attributes, commands, events, keyboard map, and copy-pasteable CSS for each element.

Live demo ​

The following runs a real pd-disclosure, wired with nothing but the markup from the first example on this page — no JavaScript beyond what the library itself registers. Watch data-state flip in your devtools as you toggle it.

Ships in 3–5 business days. Free returns within 30 days.