Widget Attributes Reference

Complete reference for all data attributes supported by the Ekoo widget element.

💡

Appearance attributes are optional overrides

The widget automatically fetches its full configuration (theme, CTA texts, colors, animation, position, custom CSS) from the Ekoo backoffice based on your websiteId and productId. You only need data attributes if you want to override the remote config for a specific widget instance.

The widget auto-loads its config from the backoffice. Appearance attributes are optional overrides — no need to set them if the backoffice is configured.

Core attributes

data-ekooReq

string

Your Ekoo website UUID. Found in the backoffice → Site settings.

data-ekoo-product-idReq

string

Product reference (must match exactly what is in your Ekoo catalog).

data-ekoo-locale

string·default: auto

Locale code: fr, en, es, it, de, ar, cn, tw, hk, jp, kr, nl, tr, pl, pt, lu, be, ru. "auto" = navigator.language detection.

data-ekoo-variant

string

Stable reference of a widget configuration. The product, its audios, and its reviewers still come from data-ekoo-product-id; only the widget styling changes.

data-ekoo-review-id

string

ID of a specific audio review. If omitted, the first published review is used.

data-ekoo-on-event

string (fn name)

Name of a global window function called on each widget event (printed, played-0, played-25…).

Appearance — backoffice overrides

data-ekoo-direction

normal | reverse·default: normal

Expansion direction. normal = left-to-right, reverse = right-to-left.

data-ekoo-scale

number·default: 1

Scale factor (e.g. "1.2" for 20% larger).

data-ekoo-animation

string·default: pulse

Animation type for the widget icon at rest.

data-ekoo-animation-duration

string·default: continuous

Animation duration.

data-ekoo-always-open

boolean·default: false

If "true", the widget stays permanently expanded.

data-ekoo-show-image

boolean·default: true

Show or hide the product image in the widget.

data-ekoo-not-fully-clickable

boolean·default: false

If "true", only the play button is clickable.

data-ekoo-autoplay

boolean·default: false

Automatically start audio playback on load.

data-ekoo-show-transcript

boolean·default: false

Show a button to read the audio transcript.

data-ekoo-show-speed-button

boolean·default: false

Show a playback speed control.

data-ekoo-closed-state-main-text

string

Main CTA text shown when the widget is collapsed.

data-ekoo-closed-state-secondary-text

string

Secondary text below the CTA when the widget is collapsed.

SPA & Shadow DOM

data-ekoo-mode

spa | static·default: auto

Forces rendering mode. Auto-detected (Next.js, Nuxt, React, Vue, Angular, Sapper). Only use if auto-detection fails.

data-shadow-mode

open | closed·default: open

"open" (default) enables inspection, external CSS access and analytics tracking. Set to "closed" to fully isolate the widget.

Global JS config

window.EKOO_FORCE_SPA = true

Forces SPA mode globally (alternative to data-ekoo-mode="spa" on each widget).

window.ekooShadowMode = "open"

Global Shadow DOM mode (alternative to data-shadow-mode on each widget).

Core Attributes

Attribute	Required	Type	Description	Default
`data-ekoo`	Required	string	Your unique Ekoo website identifier (websiteId)	—
`data-ekoo-product-id`	Required	string	Product identifier matching your Ekoo catalog	—
`data-ekoo-locale`	Optional	string	Ekoo locale code (e.g., "fr", "en", "cn"). See the Locales page for the full list.	Auto-detected
`data-ekoo-variant`	Optional	string	Reference of the widget configuration to apply (e.g. "homepage", "product-page"). Only changes the widget styling — product, audios and reviewers still come from data-ekoo-product-id.	—
`data-ekoo-on-event`	Optional	string	Name of a global window function to call on widget events (printed, played, etc.)	—
`data-ekoo-review-id`	Optional	string	Target a specific audio review by ID	—

Appearance Attributes

Attribute	Type	Description	Default
`data-ekoo-direction`	`"normal"` \| `"reverse"`	Expansion direction of the widget bar	"normal"
`data-ekoo-scale`	string (numeric)	Scale factor for the widget (e.g., "1.2")	—
`data-ekoo-animation`	string	Animation type. Default is a pulsing rings effect.	"pulse"
`data-ekoo-animation-duration`	string	Animation duration. Default loops indefinitely.	"continuous"
`data-ekoo-always-open`	boolean string	If "true", widget stays expanded and cannot be collapsed	—
`data-ekoo-autoplay`	boolean string	Auto-play audio on load	—
`data-ekoo-show-transcript`	boolean string	Show transcript button	—
`data-ekoo-show-speed-button`	boolean string	Show playback speed control	—
`data-ekoo-closed-state-main-text`	string	CTA text when widget is collapsed	—
`data-ekoo-closed-state-secondary-text`	string	Secondary text when collapsed	—
`data-ekoo-show-image`	boolean string	Show product image	"true"
`data-ekoo-not-fully-clickable`	boolean string	Restrict click zone to play button only	—

SPA & Shadow DOM

Attribute	Type	Description	Default
`data-ekoo-mode`	`"spa"` \| `"static"`	Forces SPA or static rendering mode. By default, the widget auto-detects SPA frameworks (Next.js, Nuxt, React, Vue, Angular, Sapper). Use this only if auto-detection fails.	Auto-detected
`data-shadow-mode`	`"open"` \| `"closed"`	Shadow DOM mode: "open" allows external CSS access and analytics tracking, "closed" provides full isolation	"open"

Global JavaScript Configuration

These global variables affect all widgets on the page. Set them before loading the Ekoo script.

Variable	Type	Description
`window.EKOO_FORCE_SPA`	boolean	Force SPA mode for all widgets on the page
`window.ekooShadowMode`	string	Set Shadow DOM mode globally ("open" or "closed")

Global JS configuration

html

1<script>
2  // Force SPA mode for all widgets on the page
3  window.EKOO_FORCE_SPA = true;
4
5  // Set Shadow DOM mode globally (default: "open")
6  window.ekooShadowMode = "closed";
7</script>
8
9<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>

Detailed Descriptions

data-ekoo

Your unique website identifier (websiteId), found in the Ekoo backoffice under your site settings. This value must match exactly — it is used to fetch your widget configuration, styling, and associated audio content. Placed on the widget container (div or ekoo-widget), not on the script tag.

data-ekoo-product-id

Links the widget to a specific product in your Ekoo catalog. The value must match exactly what is configured in the Ekoo backoffice. This attribute is case-sensitive — ensure it corresponds precisely to your product reference.

data-ekoo-locale

Filters audio content by language using an Ekoo locale code (e.g., "fr", "en"). If omitted, Ekoo uses browser language detection to determine the most appropriate content. When no matching locale is found, the widget falls back to displaying all available audio.

data-ekoo-variant

Picks which widget configuration to apply by its reference. Each widget configuration in the backoffice has a stable reference you choose yourself (for example homepage or product-page); set that value here to load the matching configuration.

The product, its audios and its reviewers are always resolved from data-ekoo-product-id. This attribute only changes the widget itself — its theme, CTA texts, animation, position, custom CSS. It lets you reuse the same product on different parts of your site with different widget styles, without duplicating it.

When the widget loads, Ekoo looks up the configuration in this order, scoped to your website and the current widget type:

The configuration whose reference matches the attribute value.
For older integrations, a configuration whose name matches the value.
The configuration attached to the product.
Your website's default configuration.

References are unique within a website and widget type, so the same reference can be reused across different widget types (e.g. standalone and carousel) without collision. If the attribute is omitted, the lookup starts at step 3.

data-ekoo-mode

Forces the widget rendering mode. The widget auto-detects SPA frameworks (Next.js, Nuxt, React, Vue, Angular, Sapper) and switches to SPA mode automatically. Set this to "spa" only if auto-detection fails, or "static" to force static rendering.

data-shadow-mode

Controls Shadow DOM encapsulation for the widget. The default "open" allows external CSS access to the widget internals, DevTools inspection and analytics tracking. Set to "closed" if you need full style isolation, preventing your page styles from affecting the widget and vice versa.

Usage Examples

Via HTML Attributes

Complete HTML attributes

html

1<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
2
3<ekoo-widget
4  data-ekoo="abc123"
5  data-ekoo-product-id="SKU-001"
6  data-ekoo-locale="fr"
7  data-ekoo-on-event="onEkooEvent"
8></ekoo-widget>

Via window.ekooOptions

JavaScript configuration

html

1<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
2
3<script>
4  window.ekooOptions = {
5    websiteId: "abc123",
6    widgets: [
7      {
8        nodeId: "ekoo-container",     // string (element ID) or function returning an HTMLElement
9        productId: "SKU-001",          // string or function returning a string
10        locale: "fr"                   // string or function returning a string (optional)
11      }
12    ]
13  };
14</script>
15
16<div id="ekoo-container"></div>

Via Custom Element

The <ekoo-widget> element is an alternative to the <div> with data-ekoo attributes:

Custom element

html

1<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
2
3<ekoo-widget
4  data-ekoo="abc123"
5  data-ekoo-product-id="SKU-001"
6  data-ekoo-locale="fr"
7></ekoo-widget>

ℹ️

Attribute Precedence

Data attributes take precedence over ekooOptions when both are specified. Use ekooOptions for global defaults and data attributes for per-widget overrides.

Related Resources

JavaScript API — Programmatic widget control functions
Events Reference — All events emitted by Ekoo widgets