Skip to content

Dynamic grid — <pd-dynamic-grid> ​

Open the live playground › — drag-resizable container with real-time breakpoint, item-count, and RTL controls. The switch follows the container, never the viewport: narrow the box on a full-width desktop window and it becomes a carousel.

Which CSS is bundled, and which is yours

Three tiers. Bundled, always-on (styles/base.css, optional include): functional guards only — for this component, just pd-dynamic-grid { display: block } (custom elements default to inline, which breaks container-type). Bundled, opt-in (styles/structure.css): the carousel skeleton — column flow, overflow, snap, 100%-columns — mechanics every project would retype identically, activated per instance and overridable by any theme rule. Yours: everything else on this page — the grid layout, the breakpoint, sizes, gaps, buttons, dots, indicators. No bundled rule ever carries visual design, so nothing here fights your design system (see Styling).

A collection of items that theme CSS lays out as a grid and, below a container-query breakpoint, as a one-row scroll-snap carousel. The component follows the library's CSS-first rule to its logical end: layout, the breakpoint, snapping, and smoothness are entirely your CSS — the element never measures its container to pick a mode and has no breakpoint attribute (its one ResizeObserver watches the scroller's own box purely to keep edge state fresh — see below). Its JavaScript is only what CSS can't do cross-browser today:

  • --pd-prev / --pd-next invoker commands that page the scroller (RTL-aware, cumulative across rapid clicks, clamped at the edges),
  • edge state: data-at-start / data-at-end, with aria-disabled="true" and tabindex="-1" kept in sync on unavailable prev/next buttons,
  • scroller accessibility: tabindex="0" (Safari has no keyboard-focusable-scroller behavior), an accessible name from label, and role="group" on non-list scrollers (lists keep their list role — overriding it would orphan the <li> semantics).
html
<pd-dynamic-grid label="Best sellers">
  <div class="rail-controls">
    <button command="--pd-prev" aria-label="Previous items">‹</button>
    <button command="--pd-next" aria-label="Next items">›</button>
  </div>
  <ul data-scroller>
    <li><!-- product card --></li>
    …
  </ul>
</pd-dynamic-grid>

The scroller is the [data-scroller] descendant (or the first ul/ol). Note there are no ids: in-component prev/next buttons without commandfor are auto-pointed at the scroller — they're ordinary native invokers afterwards, so buttons outside the component work too with an explicit commandfor. The buttons are optional: a native scroll container is exempt from WCAG 2.5.7 (scrollbars, keyboard, and touch are UA-provided alternatives), so a buttonless rail is valid — but ship them in carousel mode anyway; they're the only discoverable affordance most mouse users get.

styles/structure.css ships the carousel mechanics — the rules whose absence breaks paging rather than looks:

css
/* what the skeleton applies (inside @layer pd-structure, zero specificity) */
[data-scroller] {
  display: grid;
  grid-auto-flow: column;
  grid-auto-columns: 100%;
  grid-template-columns: none;
  overflow-x: auto;
  scroll-snap-type: x mandatory;
}
[data-scroller] > * { scroll-snap-align: start; }

Two activations:

html
<!-- 1. Static — always a carousel (product-tile sliders): -->
<pd-dynamic-grid layout="carousel" label="Images">…</pd-dynamic-grid>
css
/* 2. Responsive — YOU own the breakpoint, the skeleton follows the flag
      (style queries: Chrome 111+ / Safari 18+ / Firefox 151+): */
.rail-section { container-type: inline-size; } /* any ancestor wrapper */
@container (width < 40rem) {
  pd-dynamic-grid { --pd-layout: carousel; }
}

Two placements in that recipe are load-bearing, both forced by how CSS resolves queries:

  • The flag goes on pd-dynamic-grid, never on the scroller. The skeleton activates via @container style(--pd-layout: carousel), and a style() query evaluates the custom property on the styled element's parent — never on the element itself. Declared on pd-dynamic-grid, the flag inherits down to the scroller's parent through any wrapper; declared on [data-scroller] it can never match.
  • The width query watches an ancestor wrapper, not pd-dynamic-grid. No element can respond to its own size query, and the flag has to land on pd-dynamic-grid — so container-type goes one level up (the wrapping section usually already exists in theme markup).

Your theme still sets item widths (grid-auto-columns: 70cqw for peeking cards), scroll-behavior, gaps, and button visibility — override anything: the skeleton sits in a layer with zero-specificity selectors, so any theme rule wins. Prefer writing it yourself (or need pre-style-query browsers for the responsive case)? The manual recipe below produces the same carousel mechanics — and because it styles only the element's descendants, it can keep container-type on pd-dynamic-grid itself.

Your CSS: the whole mode switch (the manual alternative) ​

css
pd-dynamic-grid {
  container-type: inline-size;
}

pd-dynamic-grid [data-scroller] {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(10rem, 1fr));
  gap: 0.75rem;
}

.rail-controls {
  display: none;
}

/* Below the CONTAINER breakpoint — not the viewport — become a carousel. */
@container (width < 40rem) {
  pd-dynamic-grid [data-scroller] {
    grid-auto-flow: column;
    grid-auto-columns: 70cqw; /* peek the next card */
    grid-template-columns: none;
    overflow-x: auto;
    scroll-snap-type: x mandatory;
    scroll-behavior: smooth;
  }
  pd-dynamic-grid [data-scroller] > * {
    scroll-snap-align: start;
  }
  .rail-controls {
    display: flex;
  }
}

@media (prefers-reduced-motion: reduce) {
  pd-dynamic-grid [data-scroller] {
    scroll-behavior: auto; /* commands follow this automatically */
  }
}

pd-dynamic-grid button[aria-disabled='true'] {
  opacity: 0.35;
}

Container queries and scroll-snap are Baseline widely available — this works in every current browser with zero JavaScript involved in the switch. Because the query watches the container, the same component becomes a carousel in a narrow sidebar while staying a grid in the main column, on the same viewport.

Behavior details ​

SurfaceBehavior
--pd-prev / --pd-nextScroll by one page (clientWidth). Rapid activations accumulate — a double-click advances two pages even mid-smooth-scroll. behavior: 'auto' defers to your scroll-behavior (and your reduced-motion rule).
data-at-start / data-at-endToggled on pd-dynamic-grid from passive scroll events, connect, each command, and a scroller-only ResizeObserver (so a container-query mode flip or phone rotation never leaves stale state). Both set when nothing overflows (grid mode).
aria-disabled / tabindex on buttonsUnavailable arrows get aria-disabled="true" and tabindex="-1", so subsequent Tab navigation skips them while a control that becomes unavailable can retain focus. Edge activation is suppressed. Author-set tabindex is restored when the arrow becomes available.
refresh()Re-reads edge state after you mutate the contents (adding items grows scrollWidth without resizing the observed box, so the observer can't see it).
Auto-wiringIn-component --pd-prev/--pd-next buttons lacking commandfor get it set to the scroller's id at connect (buttons of a nested grid excluded). Explicit commandfor always wins.
label attributeBecomes the scroller's aria-label (skipped when you set aria-label/aria-labelledby yourself; dev-warns if the scroller ends up nameless).

Markup contract ​

PartRules
<pd-dynamic-grid>The container-query boundary (container-type: inline-size in your CSS) and the element that carries data-at-start/data-at-end.
ScrollerThe [data-scroller] descendant, else the first ul/ol. Gets an id if missing (pd-grid-N). Missing entirely ⇒ dev warning, component stays inert.
label attributeCopied to the scroller as aria-label unless you set aria-label/aria-labelledby on it yourself. A nameless scroller dev-warns.
ButtonsOptional. Inside the component: just `command="--pd-prev
ItemsAnything. Lists keep their list semantics (the component never overrides a ul/ol role); non-list scrollers get role="group".

Tailwind recipe ​

The same switch with utility classes (Tailwind v4 supports container queries natively — @container on the parent, @max-* variants on the children):

html
<pd-dynamic-grid label="Best sellers" class="@container grid gap-3">
  <div class="hidden @max-2xl:flex justify-end gap-2">
    <button command="--pd-prev" aria-label="Previous items" class="size-9 rounded-full border aria-disabled:opacity-30">‹</button>
    <button command="--pd-next" aria-label="Next items" class="size-9 rounded-full border aria-disabled:opacity-30">›</button>
  </div>
  <ul data-scroller class="grid grid-cols-[repeat(auto-fill,minmax(10rem,1fr))] gap-3
       @max-2xl:grid-flow-col @max-2xl:auto-cols-[70cqw] @max-2xl:grid-cols-none
       @max-2xl:overflow-x-auto @max-2xl:snap-x @max-2xl:snap-mandatory @max-2xl:scroll-smooth
       motion-reduce:scroll-auto">
    <li class="@max-2xl:snap-start">…</li>
  </ul>
</pd-dynamic-grid>

Shopify section example ​

Liquid renders the items; the component adds behavior on top (this is the only page category where Liquid appears — the library itself contains none):

liquid
<pd-dynamic-grid label="{{ section.settings.heading | escape }}">
  <div class="rail-controls">
    <button command="--pd-prev" aria-label="{{ 'general.previous' | t }}">‹</button>
    <button command="--pd-next" aria-label="{{ 'general.next' | t }}">›</button>
  </div>
  <ul data-scroller>
    {% for product in collections[section.settings.collection].products limit: 12 %}
      <li>{% render 'product-card', product: product %}</li>
    {% endfor %}
  </ul>
</pd-dynamic-grid>

Because the breakpoint is a container query, the same section works in a full-width slot, a two-column layout, or a sidebar without any section settings for "mobile layout" — the container decides. If merchants re-order sections or the Theme Editor injects content, call refresh() from your section's shopify:section:load handler if you mutate the rail's contents.

Before JS loads / without JS ​

The rail degrades to exactly what CSS says it is: grid mode is a plain grid; carousel mode is a native scroll container — touch, trackpad, scrollbars, and (once focused) arrow keys all work with zero JS. The buttons are the only inert part (they're invokers with a custom command, which has no native default), so keep them hidden until definition if you want (your CSS):

css
pd-dynamic-grid:not(:defined) .rail-controls {
  display: none;
}

RTL ​

Nothing to configure: --pd-prev/--pd-next are logical. Under direction: rtl the component negates the scroll delta and reads edge positions by magnitude (Blink and Gecko both report negative scrollLeft in RTL), so "next" always means forward through the list. Try the RTL toggle in the playground.

Progressive enhancement (Chromium-only CSS, optional) ​

Edge-state styling without waiting for JS, where supported — harmless elsewhere (your CSS):

css
@supports (container-type: scroll-state) {
  .rail-scroll-state {
    container-type: scroll-state;
  }
  @container scroll-state(scrollable: inline-end) {
    /* e.g. show a fade hint on the trailing edge */
  }
}

Prefer the component's data-at-start/data-at-end for anything functional — they're cross-browser. Skip ::column-generated ::scroll-marker dots entirely (no accessible-name mechanism yet — WCAG 4.1.2).

Styled example › — collection tiles in The Clinic design, one slide per view with hover arrows, showing four indicator styles side by side: round dots; a segmented scrollbar-like bar built from the goto buttons (it keeps tap-to-jump and aria-current — a fake scrollbar that stayed interactive); the same bar with an anchor-positioned sliding thumb (anchor-name on the aria-current segment, insets transitioned so the thumb glides between segments — Chrome 125+/Safari 26+/Firefox 147+, with an @supports fallback to per-segment coloring); and the decorative fake scrollbar from the measured properties (arrows do the driving).

There is no separate carousel element — this is the carousel primitive. Apply the carousel CSS unconditionally (no container query) with 100%-width slides, and add dots via --pd-goto (the invoker's value is the slide index; in-component dots need no commandfor):

html
<pd-dynamic-grid label="Images — Vitamin C Serum">
  <div data-scroller aria-roledescription="carousel">
    <div role="group" aria-roledescription="slide" aria-label="1 of 3">…</div>
    <div role="group" aria-roledescription="slide" aria-label="2 of 3">…</div>
    <div role="group" aria-roledescription="slide" aria-label="3 of 3">…</div>
  </div>
  <button command="--pd-prev" aria-label="Previous image">‹</button>
  <button command="--pd-next" aria-label="Next image">›</button>
  <button command="--pd-goto" value="0" aria-label="Image 1 of 3"></button>
  <button command="--pd-goto" value="1" aria-label="Image 2 of 3"></button>
  <button command="--pd-goto" value="2" aria-label="Image 3 of 3"></button>
</pd-dynamic-grid>

When any --pd-goto invoker targets the scroller, the component tracks the active index: data-index="n" on the element and aria-current="true" on the matching dot — following user scrolling and swipes too, not just commands. Rails without dots never pay for the per-item measurement.

The markup rules for single-slide-per-view usage (they differ from multi-card rails on purpose):

  • Use a div scroller, not a list — slides carry role="group" + aria-roledescription="slide" + an "N of M" label per APG, and role="group" children inside a ul would break list semantics.
  • Active dot = aria-current="true". APG's grouped-picker variant suggests aria-disabled on the current dot, but Dawn, Swiper, and Embla have all converged on aria-current (true/absent) — buttons can't validly carry aria-selected, and MDN's "current item within a set" is exactly this case. We follow the convention, deliberately.
  • Activation never moves focus (APG: users must be able to repeat-activate controls).
  • No live region. Every ecosystem implementation gates aria-live on auto-rotation, which this component doesn't do; for user-initiated changes the dot's own label already announces position. Add one yourself only if slides carry meaningful text content.
  • Focusables inside slides just work: because this is native scroll (not transforms), tabbing to a link in an off-screen slide scrolls it into view via the browser's own behavior, and the index tracking follows the resulting scroll event.
  • No looping — native scroll can't wrap seamlessly; the edge state tells your CSS to fade the arrows instead.

Signalling "there's more" — ranked (all recipes are your CSS) ​

  1. Peeking cards (free, strongest). Size carousel items so the next card is partially visible (grid-auto-columns: 70cqw). A cut-off card is the most universally understood overflow cue; every recipe on this page already does it. Start here.

  2. Edge fade (zero new machinery). A gradient scrim on whichever edge still has content, keyed off the published edge attributes:

    css
    pd-dynamic-grid { position: relative; }
    pd-dynamic-grid::after {
      content: '';
      position: absolute;
      inset-block: 0;
      inset-inline-end: 0;
      inline-size: 3rem;
      background: linear-gradient(to var(--edge-end, right), transparent, var(--page-bg, #fff));
      pointer-events: none;
      opacity: 1;
      transition: opacity 200ms ease;
    }
    pd-dynamic-grid[data-at-end]::after { opacity: 0; }
  3. Decorative progress bar (the "fake scrollbar"). Built entirely from the two measured custom properties the component publishes — --pd-scroll-progress (0–1 logical position, RTL-agnostic) and --pd-scroll-extent (0–1 visible fraction):

    css
    .rail-progress {
      block-size: 2px;
      border-radius: 99px;
      background: var(--line, #e5e5e5);
    }
    .rail-progress::before {
      content: '';
      display: block;
      block-size: 100%;
      border-radius: inherit;
      background: currentColor;
      inline-size: calc(var(--pd-scroll-extent, 1) * 100%);
      margin-inline-start: calc(
        var(--pd-scroll-progress, 0) * (100% - var(--pd-scroll-extent, 1) * 100%)
      );
    }
    /* Nothing to scroll → nothing to show */
    pd-dynamic-grid[data-at-start][data-at-end] .rail-progress { display: none; }

    Logical properties keep it RTL-correct for free. Mark the element aria-hidden="true" — it's decoration; the scroller itself is the interactive, assistive-tech-visible surface.

  4. The real scrollbar, styled. scrollbar-width: thin; scrollbar-color: var(--ink) transparent; on the scroller is Baseline and gives a functional bar. This is the only sanctioned way to get a draggable bar — an interactive fake scrollbar is deliberately unsupported (pointer capture, keyboard, and AT semantics for no gain over the native one).

    The inverse is equally legitimate: once you ship arrows plus one of the signals above, scrollbar-width: none removes the now-redundant native bar entirely (the styled demos do this). Nothing is lost — wheel, trackpad, touch, and arrow keys on the focusable scroller all still scroll; only the visual duplicate goes.

  5. Scroll-driven animation (@supports, Chromium + Safari). The same bar with zero JS involvement: animation-timeline: scroll(x self) on a progress element. Firefox still ships it behind a flag, so treat it as polish on top of option 3, not a replacement.

What it deliberately isn't ​

  • Not the APG carousel. A many-card product rail isn't a single-slide rotator: no aria-roledescription="carousel", no per-card "slide 7 of 30" announcements, no auto-rotation (so no pause control is required). Keyboard users Tab to the cards' links or focus the scroller and use arrow keys.
  • No pagination dots. Chromium's ::scroll-marker can add them in pure CSS as progressive enhancement (@supports selector(::scroll-marker)) — but don't use ::column-generated markers: they currently have no accessible-name mechanism (WCAG 4.1.2 violation).
  • No dedicated button elements. A pd-carousel-button-start/end element pair was considered and rejected: it would break the invoker-first and bring-your-own-<button> hard rules for zero gain — auto-wiring already removes the ceremony, and --pd-prev/--pd-next are logical (RTL-aware) already.
  • No JS mode bridge. If your theme JS thinks it needs to know which mode is active, restructure so it doesn't — that's what the container query is for.