Ionic / Capacitor Integration

Use the <ekoo-widget> custom element in your Ionic applications (React, Vue, Angular)

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

Overview

In an Ionic / Capacitor context, the Ekoo widget is used via the <ekoo-widget> custom element. The script is loaded once in index.html and the lifecycle is managed through the Ionic hooks of each framework.

  • ekooLoad() — call when the view containing the widget appears.
  • ekooUnload() — call when the view disappears.
  • ekooReload() — to force a complete widget refresh.

1. Load the Script in index.html

Add the Ekoo script to the <head> of your index.html. It will be loaded once when the application starts.

index.html
html
1<head>
2  <meta charset="UTF-8" />
3  <title>My App</title>
4  <script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
5</head>

2. Use the Custom Element

Place the <ekoo-widget> custom element in your template with the following attributes:

Custom element
html
1<ekoo-widget
2  data-ekoo="YOUR_WEBSITE_ID"
3  data-ekoo-product-id="MY_PRODUCT_ID"
4  data-ekoo-locale="fr"
5  data-shadow-mode="open"
6></ekoo-widget>
ℹ️

Note

As of widget 4.0.0, "open" is the default Shadow DOM mode, which ensures the widget works correctly as a Web Component in the Ionic context. The data-shadow-mode attribute can therefore be omitted.

Key Attributes

AttributeStatusDescription
data-ekooRequiredYour unique Ekoo website identifier.
data-product-idRequiredThe product ID matching your Ekoo catalog.
data-ekoo-variantOptionalReference of a widget configuration saved in the backoffice (e.g. "homepage"). Picks the styling to apply; product, audios and reviewers still come from data-ekoo-product-id.
data-shadow-modeOptional"open" is now the default (widget 4.0.0). Only set to "closed" if you need full style isolation.

3. Dynamic Product ID

The <ekoo-widget> custom element observes attribute changes. To update the product ID dynamically, use setAttribute:

Dynamic product ID update
javascript
1const widget = document.querySelector('ekoo-widget')
2if (widget) {
3  widget.setAttribute('data-ekoo-product-id', newProductId)
4}
💡

ekooReload() after multiple changes

If you notice visual inconsistencies after several product changes, call window.ekooReload() to force a complete widget re-initialization.

4. Ionic React

pages/ProductPage.tsx — Ionic React
tsx
1import React from 'react'
2import {
3  IonContent,
4  IonPage,
5  useIonViewDidEnter,
6  useIonViewWillLeave,
7} from '@ionic/react'
8
9interface ProductPageProps {
10  productId: string
11}
12
13const ProductPage: React.FC<ProductPageProps> = ({ productId }) => {
14  useIonViewDidEnter(() => {
15    window.ekooLoad?.()
16  })
17
18  useIonViewWillLeave(() => {
19    window.ekooUnload?.()
20  })
21
22  return (
23    <IonPage>
24      <IonContent>
25        <h1>My product</h1>
26        {/* @ts-expect-error — custom element not typed by default */}
27        <ekoo-widget
28          data-ekoo="YOUR_WEBSITE_ID"
29          data-ekoo-product-id={productId}
30          data-ekoo-locale="fr"
31          data-shadow-mode="open"
32        />
33      </IonContent>
34    </IonPage>
35  )
36}
37
38export default ProductPage

5. Ionic Vue

views/ProductPage.vue — Ionic Vue
vue
1<template>
2  <ion-page>
3    <ion-content>
4      <h1>My product</h1>
5      <ekoo-widget
6        data-ekoo="YOUR_WEBSITE_ID"
7        :data-ekoo-product-id="productId"
8        data-ekoo-locale="fr"
9        data-shadow-mode="open"
10      />
11    </ion-content>
12  </ion-page>
13</template>
14
15<script setup lang="ts">
16import { IonPage, IonContent, onIonViewDidEnter, onIonViewWillLeave } from '@ionic/vue'
17
18defineProps<{
19  productId: string
20}>()
21
22onIonViewDidEnter(() => {
23  window.ekooLoad?.()
24})
25
26onIonViewWillLeave(() => {
27  window.ekooUnload?.()
28})
29</script>
💡

Vue: declare the custom element

To avoid Vue warnings about the custom element, add ekoo-widget to the compilerOptions.isCustomElement configuration in your vite.config.ts.

6. Ionic Angular

For Angular, you must add CUSTOM_ELEMENTS_SCHEMA to the module or component that uses the custom element:

product.page.ts — Ionic Angular
typescript
1import { Component } from '@angular/core'
2import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
3import { ViewDidEnter, ViewWillLeave } from '@ionic/angular'
4
5@Component({
6  selector: 'app-product',
7  schemas: [CUSTOM_ELEMENTS_SCHEMA],
8  template: `
9    <ion-content>
10      <h1>My product</h1>
11      <ekoo-widget
12        data-ekoo="YOUR_WEBSITE_ID"
13        [attr.data-ekoo-product-id]="productId"
14        data-ekoo-locale="fr"
15        data-shadow-mode="open"
16      ></ekoo-widget>
17    </ion-content>
18  `,
19})
20export class ProductPage implements ViewDidEnter, ViewWillLeave {
21  productId = 'my-product-123'
22
23  ionViewDidEnter() {
24    (window as any).ekooLoad?.()
25  }
26
27  ionViewWillLeave() {
28    (window as any).ekooUnload?.()
29  }
30}
ℹ️

CUSTOM_ELEMENTS_SCHEMA

Without CUSTOM_ELEMENTS_SCHEMA, Angular will throw an error because it does not recognize <ekoo-widget> as a native Angular component.

Lifecycle Summary

  • View enters (visible) → ekooLoad()
  • View leaves (hidden) → ekooUnload()
  • Product ID changes → update the attribute with setAttribute
  • Visual inconsistency → ekooReload()

Go Further

Ionic / Capacitor — Documentation — Ekoo