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

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

Color scheme

color-scheme

(Recommended) Determines whether the player uses light or dark variable values

By default, the player follows the page’s native CSS color-scheme value.

The color scheme does NOT define colors directly. It selects which CSS variable values are active.

data-jw-color-scheme Compatibility fallback for browsers that do not support native CSS color-scheme

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>

(Compatibility fallback) Set data-jw-color-scheme on a wrapper element when supporting browsers that do not support the 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-content-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-content-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-content-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-content-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.
Use a font with fixed-width (tabular) numerals. Fonts with proportional numerals can cause minor layout shifts as the timestamp changes. The font can provide fixed-width numerals by default or support the OpenType tnum feature. See MDN's font-variant-numeric documentation for more information.

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

Icons

Use the following variables to replace Audio Experience icons with custom mask images. A mask image changes the icon shape but does not override its color.

To customize icon colors, use the applicable color variables in the following sections:

Menu
Primary action
Secondary action

The mask-image variables apply to both light and dark themes.

For more information about CSS mask images, see the MDN mask-image reference.

Icon	Standard	Simple	Variable
Checkmark	✅	❌	`--jw-icon-checkmark-mask-image`
CTA start	✅	✅	`--jw-icon-cta-start-mask-image`
Forward 10 seconds	✅	❌	`--jw-icon-forward-10-mask-image`
Pause	✅	✅	`--jw-icon-pause-mask-image`
Play	✅	✅	`--jw-icon-play-mask-image`
Rewind 10 seconds	✅	❌	`--jw-icon-rewind-10-mask-image`
Spinner	✅	✅	`--jw-icon-spinner-mask-image`
Volume 0	✅	❌	`--jw-icon-volume-0-mask-image`
Volume 50	✅	❌	`--jw-icon-volume-50-mask-image`
Volume 100	✅	❌	`--jw-icon-volume-100-mask-image`

Layout

UI element/state	Standard	Simple	Variable
Audio player padding	❌	✅	`--jw-body-padding`

UI element/state	Standard	Simple	Light variable	Dark variable
Checkmark in menu row	✅	❌	`--jw-action-secondary-content-color-light`	`--jw-action-secondary-content-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

📘
Primary action icon colors remain the same across default, hover, and active states. Only the background color changes between these states.

UI element/state	Standard	Simple	Light variable	Dark variable
CTA start icon	✅	✅	`--jw-action-primary-content-color-light`	`--jw-action-primary-content-color-dark`
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-content-color-light`	`--jw-action-primary-content-color-dark`
Spinner icon	✅	✅	`--jw-action-primary-content-color-light`	`--jw-action-primary-content-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 action

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-content-color-light`	`--jw-action-secondary-content-color-dark`
Next 10 seconds icon	✅	❌	`--jw-action-secondary-content-color-light`	`--jw-action-secondary-content-color-dark`
Playback speed icon	✅	❌	`--jw-action-secondary-content-color-light`	`--jw-action-secondary-content-color-dark`
Rewind 10 seconds icon	✅	❌	`--jw-action-secondary-content-color-light`	`--jw-action-secondary-content-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-content-color-light`	`--jw-action-secondary-content-color-dark`

Seekbar

📘
The --jw-thumb-default-size 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`