Skip to main content

Install the FAQ widget on your storefront

The FAQ widget is the visible accordion of FAQs on your storefront pages, so shoppers can read them. The same FAQs also reach crawlers and AI assistants as FAQPage structured data inside the page's JSON-LD @graph, which arrives when you publish the entity.

How the accordion gets onto the page depends on your platform:

Your storefrontWhat renders the accordion
BigCommerce StencilThe Schema Injector script
BigCommerce headless / CatalystYour frontend, from the FAQ API
Shopify Online StoreThe Clione FAQ app embed of Clione's Shopify app
Shopify Hydrogen / headlessYour frontend, from the FAQ API
WordPress or any other siteThe embed script, embed.js

To write FAQs, see FAQ editor. This page is only about getting them onto the storefront. Only approved FAQs are shown.

The FAQ editor is included on Growth, Pro and Agency. Showing FAQs on your storefront never uses credits.

BigCommerce — Stencil (classic storefront)​

The accordion is rendered by the Schema Injector script. Install it once from Store Settings → Schema Injector → Install — see Schema Injector. There's nothing else to paste.

Don't also add the embed.js snippet: two Clione scripts on the same page render the FAQs twice. The Schema Injector install warns you if it finds one you added by hand.

Choose where it appears​

The accordion is placed using the first of these that applies:

  1. An anchor in your theme. Add an empty element with the data-clione-faq attribute where you want the accordion — for example right after the product description in your theme files:

    <div data-clione-faq></div>

  2. The placement setting. FAQs → Advanced → Style → FAQ widget placement: insert the accordion Before the element or After the element matching a CSS selector, for all pages (Default) or per entity type (Products, Categories, Collections, Content).

  3. Otherwise, at the end of the page's main content.

On BigCommerce, the data-style-* attributes below go on that data-clione-faq element, because the script itself belongs to Script Manager.

Verify​

  1. Open a product page that has approved FAQs in an incognito window.
  2. The accordion appears where you placed it once the page has loaded.
  3. View source (Ctrl/Cmd + U) and search for FAQPage — it's inside the @graph block marked data-clione="schema-graph", once the product is published.

BigCommerce — headless / Catalyst​

Render the FAQs server-side from your frontend with the FAQ API:

const res = await fetch(
  `https://api.clione.ai/api/v1/public/faq/render?entityType=product&entityId=${productId}`,
  { headers: { 'X-API-Key': process.env.CLIONE_API_KEY } },
)
const { data } = await res.json()
// data is null when the entity has no FAQs. Otherwise:
//   data.entries    → [{ question, answer }, …]
//   data.htmlBlock  → the accordion HTML, ready to render
//   data.jsonLd     → the FAQPage object
//   data.scriptTag  → the same FAQPage, wrapped in <script type="application/ld+json">
//   data.entryCount → number of FAQs

Optional query parameters: locale and pageUrl. See FAQ API for the full reference, and Headless on Next.js.

Shopify — Online Store (Liquid themes)​

On Shopify, the accordion comes with Clione's own Shopify app — the one you install when you connect Shopify. Turn on its Clione FAQ app embed:

  1. Shopify admin → Online Store → Themes → on your live theme, click Customize.
  2. Open App embeds in the left rail.
  3. Turn on Clione FAQ (and Clione SEO, which carries the structured data).
  4. Click Save.

The accordion HTML is rendered by Shopify on the server as part of the page, so it's in the HTML even for crawlers that don't run JavaScript. When the page loads, it moves to an element with the data-clione-faq attribute if your theme has one — add <div data-clione-faq></div> where you want it — or otherwise just above the footer.

App embeds are per theme: if you switch themes, turn it on again in the new one.

Verify​

  1. Open a published product page that has approved FAQs in an incognito window.
  2. The accordion appears where you placed it.
  3. Store Settings → Schema Injector → Schema Status checks your live storefront and tells you whether the FAQ accordion is present on the page it checked.

Shopify — Hydrogen / headless​

Same as BigCommerce headless: call the FAQ API from your route loader and render the accordion HTML and the structured data in your component. See Headless on Hydrogen.

WordPress and other storefronts — the embed script​

For any other site, use the snippet that FAQs → Embed Script builds for you (platform, API key locked to your domain, styles). It looks like this:

<div id="clione-faq"></div>
<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_..."
  data-platform="generic"
  async
></script>

The script detects which entity the page is about and renders its FAQs. If detection fails on a custom theme, set it explicitly:

<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_..."
  data-entity-type="product"
  data-entity-id="123"
  async
></script>

Without data-target, the accordion goes into an element with data-clione-faq, or just before the page footer. The full attribute list is in the FAQ editor.

The embed script runs in the browser, so crawlers that don't run JavaScript don't see what it adds. If that matters for your site, render server-side with the FAQ API instead.

Allowed domains​

The API key only answers requests from the domains on its allowed list; anything else gets 403 and nothing renders. The Embed Script tab locks the key to your storefront domain for you. To change the list, go to Store Settings → API Keys. Wildcards work (*.example.com), so you can cover a staging subdomain too.

Customize the look — data-style-* attributes​

The accordion reads styling overrides from data-style-* attributes, so you can match your brand without touching CSS. Put them on the embed script tag, or — on BigCommerce Stencil — on your data-clione-faq element. Every attribute is optional; leave one out to keep the default.

AttributeDefault (BigCommerce Stencil)Default (embed script)What it controls
data-style-accentcurrentColorcurrentColorAccent colour: the open/close chevron and the rule under the heading.
data-style-fginheritinherit (questions #1a1a2e, answers #374151)Text colour for the heading, questions and answers.
data-style-bgtransparenttransparentBackground of the whole FAQ block.
data-style-borderrgba(0,0,0,0.1)#e5e7ebColour of the outline and the lines between questions.
data-style-border-width1px1pxThickness of the line between questions.
data-style-radius8px0Corner radius of the block.
data-style-fontinheritinheritFont family. Defaults to your theme's.
data-style-font-sizeinherit1rem (questions), 0.95rem (answers)Base font size for questions and answers.
data-style-spacing1em12pxPadding inside each question row.
data-style-line-height1.61.5 (questions), 1.6 (answers)Line height of the answers.
data-style-heading-weight600700Font weight of the heading.
data-style-heading-border-width02pxThickness of the rule under the heading; 0 hides it.
data-style-question-weight600600Font weight of the questions.
data-style-answer-weight400400Font weight of the answers.
data-style-max-widthnone800pxMaximum width; set one and the block centres itself. With the embed script a bare number is read as pixels; on BigCommerce write the unit (720px).
data-style-theme——On BigCommerce Stencil, dark is built in and any other value adds a clione-faq-theme-<name> class for your own CSS. With the embed script, every value only adds that class.

On the BigCommerce data-clione-faq element you can also set data-style="minimal" (layout only, no box or colour) or data-style="default" (boxed card), data-heading to change the heading text, and data-locale to pick the heading's built-in translation.

The Style the widget step of FAQs → Embed Script has a live form for colours, font, spacing, theme and max width, and writes these attributes into the snippet for you. On BigCommerce, custom CSS saved in FAQs → Advanced → Style is applied to the accordion by the Schema Injector. More examples: FAQ widget customization.

"Powered by Clione" badge​

The accordion that the embed script and the FAQ API render shows a small Powered by Clione badge. It's on by default; turn it off with Show "Powered by Clione" in the FAQ widget under Store Settings → General → Branding. During a trial it's always shown. The BigCommerce Schema Injector accordion and the Shopify Clione FAQ app embed don't show it.

Troubleshooting​

403 Forbidden in the browser console (embed script) — The page's domain isn't in the API key's allowed domains. Update the list under Store Settings → API Keys.

The accordion is empty or missing on some pages — Those entities have no approved FAQs. Open the entity in Clione → FAQs tab and add or approve some, or link a library answer.

The FAQs appear twice — Two Clione surfaces are rendering on the same page: the embed script on top of the Schema Injector (BigCommerce) or the Clione FAQ app embed (Shopify), or the embed script loaded twice. Keep one.

BigCommerce: the accordion appears in the wrong place — Add a data-clione-faq element where you want it, or set FAQ widget placement. An anchor in the page always wins over the placement setting.

Shopify: no accordion at all — Check that Clione FAQ is on and saved in your live theme, and that Clione's Shopify app is installed. Then run Schema Status on the page.