Audio Experience Customization Reference

You can customize the Audio Experience player to match your site’s design system. Styling is controlled with CSS custom properties that support both light and dark themes.

Audio Experience styling has two parts.

Part	Configuration	Description
Color scheme	`color-scheme` `data‑jw‑color‑scheme`	Determines whether the player uses light or dark variable values By default, the player follows the page’s native CSS `color-scheme` value. Use `data-jw-color-scheme` when supporting browsers that do not support native `color-scheme`. The color scheme does NOT define colors directly. It selects which CSS variable values are active.
CSS variables	`--jw--light` `--jw--dark`	Define the actual colors used by the player UI

Audio Experience styling is available in standard and simple layouts. While both layouts use the same styling system, the simple layout includes fewer UI elements, so only a subset of variables affect it.

Apply custom styling

Follow these steps to apply custom styling:

Define the light and dark CSS custom property values.
💡
You can copy and edit the Recommended defaults.

Scope the variables to :root, body, or an element that wraps the player.

🚧
Do not define Audio Experience styling variables on the html element. Variables set on html may not override the default player styles.
```
:root {
  /* Applies globally */
}

body {
  /* Applies across the page */
}

.audio-theme-brand {
  /* Applies only to elements inside this wrapper class */
}
```

Add those CSS custom property values to one of the following:
- Your existing stylesheet
- A new stylesheet
- An inline <style> block

Add the inline <style> block or reference to your stylesheet in the <head> section of your HTML page.

<!DOCTYPE html>
<html>
  <head>
    ...
    <link rel="stylesheet" href="custom_style.css">
  </head>
  <body>
    ...
  </body>
</html>

(Optional) To style multiple Audio Experience players differently on the same page, apply the style or a wrapper class that matches the scoped variables defined in step 2.

<!-- Force dark theme on a specific player -->

<div style="color-scheme: dark;">
  <!-- Audio Experience placement -->
</div>

<!-- Apply a differ color theme on a specific player -->

<div class="audio-theme-brand">
  <!-- Audio Experience placement -->
</div>

<!-- Force custom color dark theme on a specific player  -->

<div style="color-scheme: dark;" class="audio-theme-brand">
  <!-- Audio Experience placement -->
</div>

(Optional) Set data-jw-color-scheme on a wrapper element when supporting browsers that do not support native CSS color-scheme.

📘
By default, Audio Experience follows the page’s color-scheme value. If no scheme is explicitly set (color-scheme: normal;), Audio Experience uses the light theme.

<!-- Force light theme variables -->

<div data-jw-color-scheme="light">
  <!-- Audio Experience placement -->
</div>

<!-- Force dark theme variables -->

<div data-jw-color-scheme="dark">
  <!-- Audio Experience placement -->
</div>

<!-- Allow the page or browser color scheme to choose -->

<div data-jw-color-scheme="light dark">
  <!-- Audio Experience placement -->
</div>

Recommended defaults

Use the default values below as a starting point when creating a custom theme.

:root {
  /* Light theme */
  --jw-body-bg-color-light: #fff;
  --jw-body-border-color-light: rgba(0, 0, 0, 0.1);
  --jw-content-primary-color-light: #282e39;
  --jw-content-secondary-color-light: rgba(0, 0, 0, 0.6);
  --jw-action-primary-icon-color-light: #282e39;
  --jw-action-primary-border-color-light: rgba(0, 0, 0, 0.2);
  --jw-action-primary-default-bg-color-light: rgba(0, 0, 0, 0.1);
  --jw-action-primary-hover-bg-color-light: rgba(0, 0, 0, 0.2);
  --jw-action-primary-active-bg-color-light: rgba(0, 0, 0, 0.4);
  --jw-action-secondary-icon-color-light: #282e39;
  --jw-action-secondary-default-bg-color-light: transparent;
  --jw-action-secondary-hover-bg-color-light: rgba(0, 0, 0, 0.1);
  --jw-action-secondary-active-bg-color-light: rgba(0, 0, 0, 0.2);
  --jw-action-secondary-border-color-light: rgba(0, 0, 0, 0.2);
  --jw-focus-ring-border-color-light: #368eff;
  --jw-fill-muted-color-light: rgba(0, 0, 0, 0.1);
  --jw-fill-moderate-color-light: rgba(0, 0, 0, 0.2);
  --jw-menu-shadow-color-light: rgba(0, 0, 0, 0.2);
  --jw-knob-shadow-color-light: rgba(255, 255, 255, 0.2);

  /* Dark theme */
  --jw-body-bg-color-dark: #000;
  --jw-body-border-color-dark: rgba(255, 255, 255, 0.2);
  --jw-content-primary-color-dark: #fff;
  --jw-content-secondary-color-dark: rgba(255, 255, 255, 0.7);
  --jw-action-primary-icon-color-dark: #fff;
  --jw-action-primary-border-color-dark: rgba(255, 255, 255, 0.2);
  --jw-action-primary-default-bg-color-dark: rgba(255, 255, 255, 0.1);
  --jw-action-primary-hover-bg-color-dark: rgba(255, 255, 255, 0.2);
  --jw-action-primary-active-bg-color-dark: rgba(255, 255, 255, 0.3);
  --jw-action-secondary-icon-color-dark: #fff;
  --jw-action-secondary-default-bg-color-dark: transparent;
  --jw-action-secondary-hover-bg-color-dark: rgba(255, 255, 255, 0.1);
  --jw-action-secondary-active-bg-color-dark: rgba(255, 255, 255, 0.2);
  --jw-action-secondary-border-color-dark: rgba(255, 255, 255, 0.2);
  --jw-focus-ring-border-color-dark: #368eff;
  --jw-fill-muted-color-dark: rgba(255, 255, 255, 0.2);
  --jw-fill-moderate-color-dark: rgba(255, 255, 255, 0.3);
  --jw-menu-shadow-color-dark: rgba(0, 0, 0, 0.7);
  --jw-knob-shadow-color-dark: rgba(255, 255, 255, 0.2);
}

CSS variable reference

The following tables list each customizable Audio Experience UI element or state, the layouts it applies to, and the corresponding light and dark CSS custom properties, where applicable.

Container

UI element/state	Standard	Simple	Light variable	Dark variable
Audio player border	✅	✅	`--jw-body-border-color-light`	`--jw-body-border-color-dark`
Audio player container	✅	✅	`--jw-body-bg-color-light`	`--jw-body-bg-color-dark`

Content

UI element/state	Standard	Simple	Light variable	Dark variable
Article title	✅	❌	`--jw-content-primary-color-light`	`--jw-content-primary-color-dark`
Powered by JWX text	✅	✅	`--jw-content-secondary-color-light`	`--jw-content-secondary-color-dark`
Timestamp text	✅	✅	`--jw-content-secondary-color-light`	`--jw-content-secondary-color-dark`

Focus and shadows

UI element/state	Standard	Simple	Light variable	Dark variable
All interactive components, focus ring	✅	✅	`--jw-focus-ring-border-color-light`	`--jw-focus-ring-border-color-dark`
Knob shadow	✅	✅	`--jw-knob-shadow-color-light`	`--jw-knob-shadow-color-dark`

Font

📘
The --jw-font-family variable sets the font family for the text elements listed below. The same font family applies to both light and dark themes.

UI element/state	Standard	Simple	Variable
Article title	✅	❌	`--jw-font-family`
Timestamp text	✅	✅	`--jw-font-family`

UI element/state	Standard	Simple	Light variable	Dark variable
Checkmark in menu row	✅	❌	`--jw-action-secondary-icon-color-light`	`--jw-action-secondary-icon-color-dark`
Menu links	✅	❌	`--jw-content-primary-color-light`	`--jw-content-primary-color-dark`
Menu row active background	✅	❌	`--jw-action-secondary-active-bg-color-light`	`--jw-action-secondary-active-bg-color-dark`
Menu row default background	✅	❌	`--jw-body-bg-color-light`	`--jw-body-bg-color-dark`
Menu row hover background	✅	❌	`--jw-action-secondary-hover-bg-color-light`	`--jw-action-secondary-hover-bg-color-dark`
Menu shadow	✅	❌	`--jw-menu-shadow-color-light`	`--jw-menu-shadow-color-dark`

Primary action

UI element/state	Standard	Simple	Light variable	Dark variable
Play/pause button active background	✅	✅	`--jw-action-primary-active-bg-color-light`	`--jw-action-primary-active-bg-color-dark`
Play/pause button border	✅	✅	`--jw-action-primary-border-color-light`	`--jw-action-primary-border-color-dark`
Play/pause button default background	✅	✅	`--jw-action-primary-default-bg-color-light`	`--jw-action-primary-default-bg-color-dark`
Play/pause button hover background	✅	✅	`--jw-action-primary-hover-bg-color-light`	`--jw-action-primary-hover-bg-color-dark`
Play/pause icon	✅	✅	`--jw-action-primary-icon-color-light`	`--jw-action-primary-icon-color-dark`

Progress and volume

UI element/state	Standard	Simple	Light variable	Dark variable
Buffer indicator	✅	✅	`--jw-fill-moderate-color-light`	`--jw-fill-moderate-color-dark`
Playback fill from progress bar	✅	✅	`--jw-content-primary-color-light`	`--jw-content-primary-color-dark`
Progress knob	✅	✅	`--jw-content-primary-color-light`	`--jw-content-primary-color-dark`
Progress rail	✅	✅	`--jw-fill-muted-color-light`	`--jw-fill-muted-color-dark`
Volume bar fill	✅	❌	`--jw-content-primary-color-light`	`--jw-content-primary-color-dark`
Volume bar rail	✅	❌	`--jw-fill-muted-color-light`	`--jw-fill-muted-color-dark`
Volume knob	✅	❌	`--jw-content-primary-color-light`	`--jw-content-primary-color-dark`

Secondary actions

UI element/state	Standard	Simple	Light variable	Dark variable
Audio track switcher border	✅	❌	`--jw-action-secondary-border-color-light`	`--jw-action-secondary-border-color-dark`
Audio track switcher icon	✅	❌	`--jw-action-secondary-icon-color-light`	`--jw-action-secondary-icon-color-dark`
Next 10 seconds icon	✅	❌	`--jw-action-secondary-icon-color-light`	`--jw-action-secondary-icon-color-dark`
Playback speed icon	✅	❌	`--jw-action-secondary-icon-color-light`	`--jw-action-secondary-icon-color-dark`
Rewind 10 seconds icon	✅	❌	`--jw-action-secondary-icon-color-light`	`--jw-action-secondary-icon-color-dark`
Secondary action buttons, active background	✅	❌	`--jw-action-secondary-active-bg-color-light`	`--jw-action-secondary-active-bg-color-dark`
Secondary action buttons, default background	✅	❌	`--jw-action-secondary-default-bg-color-light`	`--jw-action-secondary-default-bg-color-dark`
Secondary action buttons, hover background	✅	❌	`--jw-action-secondary-hover-bg-color-light`	`--jw-action-secondary-hover-bg-color-dark`
Volume button icon	✅	❌	`--jw-action-secondary-icon-color-light`	`--jw-action-secondary-icon-color-dark`

Seekbar

📘
The --jw-thumb-size-default variable controls whether the seekbar thumb appears when the visitor is not hovering over the simple player. Set the value to 12px to show the thumb by default. The same value applies to both light and dark themes.

UI element/state	Standard	Simple	Variable
Seekbar thumb	❌	✅	`--jw-thumb-default-size`

Tooltip

UI element/state	Standard	Simple	Light variable	Dark variable
Tooltip background	✅	✅	`--jw-body-bg-color-light`	`--jw-body-bg-color-dark`
Tooltip text	✅	✅	`--jw-content-primary-color-light`	`--jw-content-primary-color-dark`