Build maintainable FAQ sections for Shopify

Blocks schema — one row type merchants understand

{
  "name": "FAQ",
  "blocks": [
    {
      "type": "question",
      "name": "Question",
      "settings": [
        {
          "type": "text",
          "id": "title",
          "label": "Question",
          "default": "How long does shipping take?"
        },
        {
          "type": "richtext",
          "id": "answer",
          "label": "Answer",
          "default": "<p>Standard shipping arrives in 3–5 business days.</p>"
        }
      ]
    }
  ],
  "presets": [
    {
      "name": "FAQ",
      "blocks": [
        {
          "type": "question",
          "settings": {
            "title": "How long does shipping take?",
            "answer": "<p>Standard shipping arrives in 3–5 business days.</p>"
          }
        },
        {
          "type": "question",
          "settings": {
            "title": "What is your return policy?",
            "answer": "<p>Unworn items can be returned within 30 days.</p>"
          }
        }
      ]
    }
  ]
}

Seeded presets teach repetition. An empty block list looks broken and invites hardcoding.

Button + aria-expanded panel pattern

<div class="faq" data-faq-root>
  {% for block in section.blocks %}
    {% assign panel_id = 'FaqAnswer-' | append: section.id | append: '-' | append: block.id %}
    <div class="faq__item" {{ block.shopify_attributes }}>
      <button
        type="button"
        class="faq__question"
        id="FaqQuestion-{{ section.id }}-{{ block.id }}"
        aria-expanded="false"
        aria-controls="{{ panel_id }}"
        data-faq-trigger
      >
        {{ block.settings.title | escape }}
      </button>
      <div
        class="faq__answer rte"
        id="{{ panel_id }}"
        role="region"
        aria-labelledby="FaqQuestion-{{ section.id }}-{{ block.id }}"
        hidden
        data-faq-panel
      >
        {{ block.settings.answer }}
      </div>
    </div>
  {% endfor %}
</div>

escape the question text. Keep answer as richtext through .rte. Unique ids must include section.id and block.id so duplicates never collide.

Optional FAQPage JSON-LD from the same blocks

{% if section.blocks.size > 0 %}
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {% for block in section.blocks %}
        {
          "@type": "Question",
          "name": {{ block.settings.title | json }},
          "acceptedAnswer": {
            "@type": "Answer",
            "text": {{ block.settings.answer | strip_html | json }}
          }
        }{% unless forloop.last %},{% endunless %}
      {% endfor %}
    ]
  }
  </script>
{% endif %}

Only emit FAQPage when this section is the canonical FAQ for the URL. Duplicate FAQPage graphs on every template create junk structured data—gate carefully.

Section-scoped toggle sketch

(function () {
  const root = document.querySelector('[data-faq-root]');
  if (!root) return;

  root.querySelectorAll('[data-faq-trigger]').forEach((button) => {
    button.addEventListener('click', () => {
      const expanded = button.getAttribute('aria-expanded') === 'true';
      const panelId = button.getAttribute('aria-controls');
      const panel = root.querySelector('#' + CSS.escape(panelId));
      if (!panel) return;

      button.setAttribute('aria-expanded', String(!expanded));
      panel.hidden = expanded;
    });
  });
})();

In production, prefer a small asset loaded once per section instance or an inline script that receives section.id. The rule is isolation—not the exact bundling choice.