Skip to content

Shopify integration ​

pd-components ships zero Shopify or Liquid code (SPEC §1.2 rule 4, §1.2 rule 6) — the library knows nothing about themes, linklists, or settings_schema.json. This page is the one place in the repo where Liquid is allowed to appear, and every line of it below lives inside a fenced liquid code block so the docs site's Vue-based renderer never tries to parse it as a template expression. Copy these patterns into your theme's snippets/sections; nothing here needs to be exact, it's a starting point for wiring your linklists, collections, and shop data into the flat markup the library expects.

1. Vendor the bundle ​

Run the library's build and copy the standalone ESM bundle (polyfill inlined, all elements auto-defined — SPEC §6) into your theme's assets/ directory as pd-components.js. Load it once, site-wide, as a module script so it's deferred automatically and only ever evaluated once:

liquid
<script type="module" src="{{ 'pd-components.js' | asset_url }}"></script>

That's the entire integration surface for loading the library. There is no theme editor setting, no additional initialization call — importing define.ts (what the bundle is built from) registers every pd-* element and conditionally applies the invoker-commands polyfill as a side effect. defineAll() is idempotent, so it's safe if this script tag ends up on every template.

2. Mega menu from linklists ​

A two-level loop over a linklist builds the flat nav markup from SPEC §5.2: top-level links become the nav's tabbable stops, and any top-level link with children gets an invoker button plus a pd-nav-panel. forloop.index gives each panel a stable, collision-free id without you having to slugify titles:

liquid
<nav aria-label="Main">
  <pd-nav hover open-on-focus>
    <ul>
      {% for link in linklists.main-menu.links %}
        <li>
          <a href="{{ link.url }}"{% if link.links.size > 0 %} data-pd-hover-for="mm-{{ forloop.index }}"{% endif %}>
            {{ link.title }}
          </a>
          {% if link.links.size > 0 %}
            <button commandfor="mm-{{ forloop.index }}" command="--pd-toggle" aria-label="{{ link.title }} menu">
              <svg aria-hidden="true" width="10" height="6"><path d="M0 0l5 6 5-6z" fill="currentColor" /></svg>
            </button>
            <pd-nav-panel id="mm-{{ forloop.index }}">
              <ul>
                {% for child_link in link.links %}
                  <li><a href="{{ child_link.url }}">{{ child_link.title }}</a></li>
                {% endfor %}
              </ul>
            </pd-nav-panel>
          {% endif %}
        </li>
      {% endfor %}
    </ul>
  </pd-nav>
</nav>

Notes:

  • The panel is a flat sibling of the trigger <a>/<button> inside the same <li> — no wrapper divs. Grid the panel's columns with CSS (see the Styling guide), not with extra markup.
  • link.links is a Shopify linklist's second level; a third level isn't looped here — flatten deeper menus into the mega-menu's column content instead of nesting more pd-nav-panels, which keeps the pattern matching the library's flat-markup rule (SPEC §1.2 rule 2).
  • data-pd-hover-for is only added when the link actually has a panel, so plain links (like an "About" item with no children) never register spurious hover regions.

Reuse the identical linklists.main-menu.links data to build the mobile drawer's drilldown (SPEC §5.3/§5.4) — one Liquid source of truth for both the desktop mega menu and the mobile drilldown:

liquid
<button commandfor="mobile-menu" command="show-modal" aria-label="Open menu">☰</button>
<pd-drawer>
  <dialog id="mobile-menu" aria-label="Menu">
    <button commandfor="mobile-menu" command="close" aria-label="Close menu">✕</button>
    <pd-drilldown id="mobile-drilldown">
      <pd-drilldown-panel root>
        <ul>
          {% for link in linklists.main-menu.links %}
            <li>
              {% if link.links.size > 0 %}
                <button commandfor="dd-{{ forloop.index }}" command="--pd-drill">{{ link.title }}</button>
              {% else %}
                <a href="{{ link.url }}">{{ link.title }}</a>
              {% endif %}
            </li>
          {% endfor %}
        </ul>
      </pd-drilldown-panel>
      {% for link in linklists.main-menu.links %}
        {% if link.links.size > 0 %}
          <pd-drilldown-panel id="dd-{{ forloop.index }}" label="{{ link.title }}">
            <button commandfor="mobile-drilldown" command="--pd-back">← Back</button>
            <ul>
              {% for child_link in link.links %}
                <li><a href="{{ child_link.url }}">{{ child_link.title }}</a></li>
              {% endfor %}
            </ul>
          </pd-drilldown-panel>
        {% endif %}
      {% endfor %}
    </pd-drilldown>
  </dialog>
</pd-drawer>

The label attribute rendered onto each destination panel (bound to the link's title above) isn't decorative — it's what lets a screen reader announce which section a shopper just drilled into (see the Accessibility guide).

Reset the drilldown so the drawer always reopens at its root, rather than wherever the shopper left it. This is plain JS, not Liquid — it's the one non-Liquid script this integration needs, and it's the docs recipe from SPEC §5.4 (call reset() on the drawer's pd:closed):

html
<script type="module">
  const drawer = document.querySelector('pd-drawer')
  const drilldown = document.getElementById('mobile-drilldown')
  drawer.addEventListener('pd:closed', (event) => {
    // Ignore bubbling pd:closed events from disclosures inside the drawer.
    if (event.target === drawer) drilldown.reset()
  })
</script>

4. Brand index from collections/vendors ​

An A–Z filter (SPEC §5.5) needs two things: a static alphabet of invoker buttons, and a list whose items carry data-filter-value. Where that list's data comes from depends on how your catalog models brands.

If brands are collections (a common pattern: one collection per brand, tagged so you can find them), loop collections and filter by whatever convention your theme uses — a tag shown here:

liquid
<pd-filter id="brand-filter" for="brand-list" match="starts-with">
  {% assign letters = "a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z" | split: "," %}
  {% for letter in letters %}
    <button commandfor="brand-filter" command="--pd-filter" value="{{ letter }}">{{ letter | upcase }}</button>
  {% endfor %}
  <button commandfor="brand-filter" command="--pd-clear">All</button>
</pd-filter>
<pd-filter-status for="brand-filter">Showing {count} of {total} brands</pd-filter-status>
<ul id="brand-list">
  {% for collection in collections %}
    {% if collection.tags contains 'brand' %}
      <li data-filter-value="{{ collection.title }}">
        <a href="{{ collection.url }}">{{ collection.title }}</a>
      </li>
    {% endif %}
  {% endfor %}
</ul>

If brands are just product vendors (no dedicated collection per brand), shop.vendors gives you the shop-wide vendor list directly, linked into the all-products collection's vendor filter:

liquid
<ul id="brand-list">
  {% for vendor in shop.vendors %}
    <li data-filter-value="{{ vendor }}">
      <a href="{{ routes.all_products_collection_url }}?filter.p.vendor={{ vendor | url_param_escape }}">
        {{ vendor }}
      </a>
    </li>
  {% endfor %}
</ul>

Either way, data-filter-value must carry the exact string pd-filter compares against (its match is Unicode-fold + case-insensitive, so accents and casing are forgiving, but the letter buttons' value attributes and the list's data-filter-values need to agree on what the alphabet means for your catalog).

Settings-schema-free stance ​

pd-components has no settings_schema.json entry and never will (SPEC §1.2 rule 6: "Configuration is HTML attributes and/or JS properties/methods only. No JSON blobs, no settings schema."). Every behavioral knob documented on the component pages — hover, hover-open-delay, arrow-nav, orientation, close-on-outside-click, scroll-lock, threshold, match, toggle — is a plain HTML attribute your section or snippet renders. If you want a merchant-configurable toggle, that's an ordinary Shopify section setting driving a Liquid conditional on the attribute, exactly like any other markup decision your theme already makes — the library doesn't need to know settings exist:

liquid
{% schema %}
{
  "name": "Header",
  "settings": [
    { "type": "checkbox", "id": "enable_hover", "label": "Open mega menu on hover", "default": true }
  ]
}
{% endschema %}

<pd-nav{% if section.settings.enable_hover %} hover{% endif %} open-on-focus>
  ...
</pd-nav>

The schema block above is your section's own settings — normal Shopify practice, unrelated to and unowned by pd-components. The library only ever sees the resulting hover attribute (or its absence) on the rendered <pd-nav> tag.