Standalone Widget

The standalone widget displays a single audio as a compact icon with an information bar that expands and collapses on click. It's the most common format for presenting an audio review on a product page.

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).

Behavior

On load, the widget displays a compact icon with a call-to-action text.
On click, the information bar expands to reveal the audio player and review details.
A second click collapses the bar (unless alwaysOpen is enabled).
The widget only appears if a published audio is associated with the product.

Minimal Integration

Add the Ekoo script and a container with the data-ekoo and data-ekoo-product-id attributes:

Minimal integration

html

1<!-- Ekoo Script -->
2<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
3
4<!-- Widget container -->
5<ekoo-widget
6  data-ekoo="YOUR_WEBSITE_ID"
7  data-ekoo-product-id="YOUR_PRODUCT_ID"
8></ekoo-widget>

ℹ️

Prerequisites

The widget only appears if a published audio is associated with the product in the Ekoo backoffice. Make sure the audio is published before testing your integration.

Standalone-Specific Parameters

Parameter	Type	Default	Description
`reviewId`	string	—	Identifier of a specific review to display. If omitted, the widget shows the first published audio for the product.
`direction`	`normal` \| `reverse`	`normal`	Expansion direction of the bar. normal = standard (left-to-right), reverse = inverted (right-to-left).
`animation`	string	`pulse`	Animation type. Default is a pulsing rings effect that draws attention to the widget.
`animationDuration`	string	`continuous`	Duration of the animation. Default is continuous (loops indefinitely).
`iconListen`	string (URL)	—	URL of a custom icon for the listen button.
`chevron`	boolean	true	Show or hide the open/close chevron indicator.
`closedStateMainText`	string	—	Main text displayed when the widget is collapsed.
`closedStateSecondaryText`	string	—	Secondary text displayed below the main text in the collapsed state.
`closedStateDisplayChevron`	boolean	true	Show or hide the chevron in the collapsed state.
`alwaysOpen`	boolean	false	If enabled, the widget stays expanded and cannot be collapsed by the user.

Widget Direction

The direction parameter controls the expansion direction of the information bar:

normal (default) — Standard expansion direction (left-to-right on LTR pages).
reverse — Inverted direction. Useful for right-aligned layouts.

Animation

The widget uses a pulse animation by default — pulsing rings that draw attention to the audio player. The animation runs continuously until the user interacts with the widget.

Parameter	Default	Description
`animation`	`pulse`	Animation type. The default pulse effect creates pulsing rings around the widget icon.
`animationDuration`	`continuous`	How long the animation runs. Default is continuous (loops indefinitely).

Complete Example

Customized standalone widget

html

1<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
2
3<ekoo-widget
4  data-ekoo="YOUR_WEBSITE_ID"
5  data-ekoo-product-id="YOUR_PRODUCT_ID"
6  data-ekoo-locale="fr"
7  data-ekoo-direction="reverse"
8  data-ekoo-animation="pulse"
9  data-ekoo-always-open="true"
10  data-ekoo-closed-state-main-text="Listen to a customer review"
11  data-ekoo-closed-state-secondary-text="Verified audio"
12  data-ekoo-scale="1.2"
13  data-ekoo-on-event="onEkooEvent"
14></ekoo-widget>

💡

Remote configuration

The Ekoo widget automatically fetches its full visual configuration from the Ekoo backoffice based on your websiteId and productId. This includes: theme, colors, CTA texts, animation settings, position, and custom CSS. You don't need to set appearance attributes in your HTML — the backoffice configuration is applied automatically. Data attributes like data-ekoo-closed-state-main-text or data-ekoo-scale are only needed if you want to override the backoffice configuration for a specific widget instance.

💡

Optimize loading

For a faster widget start, load the script in the <head> with defer. See Script loading for the full pattern (preconnect, preload, per stack).

Same product, multiple widget configurations

One product can be displayed with several widget styles across your site without being duplicated. Save each style as a widget configuration in the backoffice, give it a stable reference (for example homepage or product-page), then point to it from your HTML with data-ekoo-variant:

Same product, two widget configurations

html

1<!-- Same product (same audios, same reviewers), two different widget skins. -->
2<!-- "homepage" and "product-page" are example values; replace them with the references -->
3<!-- of widget configurations saved in your backoffice. -->
4
5<!-- Homepage block -->
6<ekoo-widget
7  data-ekoo="YOUR_WEBSITE_ID"
8  data-ekoo-product-id="SKU-001"
9  data-ekoo-variant="homepage"
10></ekoo-widget>
11
12<!-- Product page block -->
13<ekoo-widget
14  data-ekoo="YOUR_WEBSITE_ID"
15  data-ekoo-product-id="SKU-001"
16  data-ekoo-variant="product-page"
17></ekoo-widget>

Both blocks render the same product, with the same audios and reviewers — only the widget styling differs.

ℹ️

If no configuration matches

Ekoo first looks for a configuration whose reference matches the attribute value. If none is found, it falls back to a legacy lookup by configuration name (for older integrations), then to the configuration attached to the product, and finally to your website's default configuration. References are unique within a website and widget type, so the widget always resolves to a single configuration.

ℹ️

Custom element syntax

You can also use <ekoo-widget> instead of a <div>:

<ekoo-widget data-ekoo="..." data-ekoo-product-id="..."></ekoo-widget>

Both syntaxes are equivalent. The Ekoo script automatically detects both.