Widget Data Attributes Reference
Every data-bn attribute for the beyondRegular embed. Required preset ID, format overrides, autoplay, product context, and common install gotchas.
Every beyondRegular widget renders from a single div with data attributes. The only required one is `data-bn-preset` pointing at your preset ID. Optional attributes let you switch format, tune autoplay, cap height, and pass a custom product handle. Paste the loader script once per page, then drop the div wherever you want the widget to appear.
The minimum install
Two tags. One script in the head or before </body>, one div where the widget should render. The script is async and idempotent, so multiple divs on the same page share one loader.
```html <script async src="https://www.itsbeyondregular.com/embed.js"></script> <div data-bn-preset="YOUR_PRESET_ID"></div> ```
`data-bn-preset` is the only required attribute. You get the preset ID from the dashboard after you save a widget. If the div is empty on load, the script mounts into it. If you inject the div later on an SPA route change or when a modal opens, the script picks it up via MutationObserver, no re-init call needed.
Format and layout attributes
The preset already carries a format, but you can override per placement. Useful when the same preset appears as a floating bubble on mobile and a carousel on desktop.
```html <div data-bn-preset="pr_abc123" data-bn-format="reel" data-bn-max-height="720" data-bn-columns="3" ></div> ```
`data-bn-format` accepts `carousel-h`, `carousel-v`, `bubble`, or `reel`. `data-bn-max-height` takes a pixel number and clamps the widget on tall screens. `data-bn-columns` only applies to horizontal carousel and reel feed. Bubble ignores columns and height, it docks to a corner set in the dashboard.
Playback and interaction
Autoplay is muted by default because browsers block sound without a user gesture. Attributes let you tune what happens on scroll and tap.
```html <div data-bn-preset="pr_abc123" data-bn-autoplay="in-view" data-bn-loop="true" data-bn-sound="tap-to-unmute" ></div> ```
`data-bn-autoplay` accepts `in-view` (plays when 50% visible), `always`, or `off`. `data-bn-loop` is `true` or `false`. `data-bn-sound` accepts `muted`, `tap-to-unmute`, or `on` (only fires after first user gesture anywhere on the page). Set `data-bn-sound="on"` only if your site already had audio interaction, otherwise Chrome will silently downgrade to muted.
Product context and attribution
On a product detail page you usually want the widget scoped to that product. Pass the handle so tags resolve to the current item first.
```html <div data-bn-preset="pr_abc123" data-bn-product="navy-cotton-tee" data-bn-currency="INR" data-bn-ref="pdp-below-fold" ></div> ```
`data-bn-product` takes a Shopify handle or catalogue SKU. `data-bn-currency` forces a currency code, otherwise the widget reads shopper geo and defaults to INR for India. `data-bn-ref` is a free-form label that lands in your analytics as the placement source, useful for A/B tests between homepage and PDP slots. On Shopify with the theme app embed, `data-bn-product` is filled from Liquid automatically.
Common install gotchas
Ordered by how often merchants hit them in support. Widget doesn't render at all: preset ID typo. Check the dashboard, IDs are case-sensitive and start with `pr_`. Blank space where the widget should be: script loading from a different domain than embed.js. Use the exact URL `https://www.itsbeyondregular.com/embed.js`, not a mirror or a stale copy.
Widget renders twice on Shopify: you have both the theme app embed enabled and a manual div on the same page. Disable one, usually the manual div. Sound never plays: `data-bn-sound="on"` set but no user gesture has fired on the page yet. Switch to `tap-to-unmute` and the widget will show an unmute affordance itself.
Bubble covers the cart drawer: set `data-bn-z-index="10"` on the div to sit below your drawer's z-index. Widget flickers on route change in a React or Vue app: give the div a stable `key` or `id` so the framework doesn't tear the node down and remount it on every state update.
Common questions
Can I mount the widget after the page loads, for example in a modal or SPA route?
Yes. embed.js runs a MutationObserver on the document body, so any div with `data-bn-preset` added after initial load gets picked up and mounted. You don't need to call an init function or re-inject the script tag. If you're using a heavy SPA framework that re-renders the same node, give the div a stable `key` or `id` so React or Vue doesn't tear it down and remount every state change. That keeps the video from restarting mid-view.
How do I pass a different preset per page without touching the script tag?
Only `data-bn-preset` changes. The script tag stays identical across every page, it's cached after first load so subsequent pages hit the browser cache. On a homepage you might use `data-bn-preset="pr_home_hero"`, on a PDP you swap to `data-bn-preset="pr_pdp_default"` with `data-bn-product` set to the current handle. On Shopify the theme app embed handles this via block settings, you pick the preset in the theme editor per section, no code changes.
What data attributes does the Shopify theme app embed set automatically?
The Liquid template renders the div with `data-bn-preset` (from block settings), `data-bn-product` (from `{{ product.handle }}` when on a product page), `data-bn-currency` (from `{{ shop.currency }}`), and `data-bn-ref` (set to the section ID). You can override any of these by editing the block's custom code field in the theme editor. Web pixel attribution is wired up on the Pro plan without any attribute changes, it reads the same preset ID.