Standalone Widget CSS Customization

The standalone widget (widget-4.0.0-standalone.js) is built as a Web Component encapsulated in an open Shadow DOM (mode: 'open'). This encapsulation protects the player from host store styles while preventing Ekoo styles from leaking onto your layout.

ℹ️

Where to apply your custom CSS?

Add your styles in the "Custom CSS" field in the Ekoo Backoffice (Branding > Widgets > Standalone > Advanced options).

The code is injected directly into the <style> block inside the Shadow DOM: you have direct access to all internal widget classes without encapsulation barriers.

Visual Anatomy & CSS Selectors

Locate every customizable element of the widget. Click any badge to copy its CSS selector, or click +CSS to copy a ready-to-use rule snippet.

Visual Anatomy & CSS SelectorsCollapsed state

Interactive Live CSS Playground

Experiment with your styles live on an isolated instance of the 4.0.0 widget. Start with the standard theme, test presets (Minimalist, Terracotta), toggle between product page and standalone view, fine-tune your CSS and copy the final snippet.

Common CSS Recipes & Advanced Tweaks

Select a recipe below to grab the exact snippet for your use case:

The standalone script dynamically applies state classes to the <ekoo-widget> element. Target them in custom CSS using :host(...):

:host(.playing) — Audio actively playing
:host(.paused) — Audio paused
:host(.ekoo-touch-preview) — Touch interaction on mobile
:host(.ekoo-transcript-open) — Transcript popup open
:host(:hover) / :host(:focus-within) — Smooth drawer expand on hover/focus

Targeting widget interaction states

css

1/* Subtle button pulse during playback */
2:host(.playing) .ekoo-widget-picture {
3  transform: scale(1.05);
4  transition: transform 0.2s ease;
5}
6
7/* Slight dimming when paused */
8:host(.paused) .ekoo-widget-picture {
9  opacity: 0.95;
10}
11
12/* Pointer cursor on hover */
13:host(:hover) .ekoo-widget-container-picture-button {
14  cursor: pointer;
15}
16
17/* Accent icon when transcript modal is open */
18:host(.ekoo-transcript-open) .ekoo-icon-book-open {
19  color: var(--my-brand-accent, #8b1538);
20}
21
22/* Reverse variant (expands to the left) */
23.ekoo-standalone-container.ekoo-reverse {
24  /* Specific right-aligned layout rules */
25}

💡

Tip: hide the drawer when collapsed

When idle, the drawer .ekoo-widget-container-player has a width of 0px. If you add borders or shadows, hide them when collapsed using:

:host(:not(:hover):not(.playing):not(.paused):not(.ekoo-transcript-open):not(.ekoo-touch-preview):not(:focus-within)) .ekoo-widget-container-player { opacity: 0 !important; border: none !important; box-shadow: none !important; }

Best Practices

Use !important when needed: The widget sets default styles inline or dynamically. Adding !important ensures your brand colors and radii take precedence.
Custom fonts: Load fonts defined in font-family within your site's <head>.
Accessibility (WCAG): Maintain a minimum 4.5:1 contrast ratio and preserve :focus-visible keyboard outlines.
Reverse layouts: If your widget expands leftward (data-ekoo-direction="reverse"), target .ekoo-standalone-container.ekoo-reverse.

ℹ️

Need different configurations per page?

Create multiple configurations in the Backoffice and map them to templates using data-ekoo-variant. See the Standalone Widget page for details.