audio
The audio element embeds sound content with native playback controls, styled variants, and an optional track listing for playlists.
Description
The <audio> element embeds audio content with native browser playback controls. Vanilla Breeze styles audio players to be block-level and full-width by default, with variants for compact and minimal layouts.
Audio handling follows a progressive enhancement approach with four layers — each functional on its own:
- Layer 1 — Native
<audio>with<source>fallback chain - Layer 2 — CSS styling:
accent-color,border-radius,color-scheme - Layer 3 — Track listing via
<details>+<ol class="track-list"> - Layer 4 —
<audio-player>web component with custom controls
When to Use
- Podcasts — Episode players with playback controls
- Music players — Song or album playback
- Sound effects — UI feedback or game audio
- Voice recordings — Interviews, voicemail, audio messages
- Audiobooks — Narrated content
Layer 1: Native Baseline
Works everywhere with no CSS or JS. Always include at least one <source> with a type attribute and a download link as the ultimate fallback.
<audio controls> <source src="track.ogg" type="audio/ogg"> <source src="track.mp3" type="audio/mpeg"> <p> Your browser does not support audio playback. <a href="track.mp3" download>Download the audio file</a>. </p></audio>Multi-Source Format Chain
List formats best-to-worst — the browser picks the first it supports.
<audio controls> <source src="audio/track.opus" type="audio/ogg; codecs=opus"> <source src="audio/track.ogg" type="audio/ogg"> <source src="audio/track.m4a" type="audio/mp4"> <source src="audio/track.mp3" type="audio/mpeg"> <p><a href="audio/track.mp3" download>Download audio (MP3)</a></p></audio>Layer 2: Styled Variants
CSS-only improvements via VB tokens. The native player gains visual polish without any new HTML.
The demo above shows all three variants: default (full-width), compact, and minimal.
Default
Full-width player with accent-color, border-radius, and color-scheme from VB tokens.
.compact
Max-width constrained (320px) for inline usage or sidebars.
<audio class="compact" controls> <source src="track.mp3" type="audio/mpeg"></audio>.minimal
Reduced height for tight layouts.
<audio class="minimal" controls> <source src="track.mp3" type="audio/mpeg"></audio>Layer 3: Track Listing
HTML + CSS only. <details>/<summary> exposes a track list that shows and hides natively. Without JS, track links navigate to the audio file. With the playlist utility loaded, clicking a track updates the audio source and plays it.
<audio controls> <source src="tracks/01-opening.mp3" type="audio/mpeg"> <source src="tracks/01-opening.ogg" type="audio/ogg"> <p><a href="tracks/01-opening.mp3" download>Download track 1</a></p></audio> <details> <summary>Track Listing</summary> <ol class="track-list"> <li data-audio-active> <a href="tracks/01-opening.mp3">01. Opening Theme</a> <span class="track-meta"><time datetime="PT2M14S">2:14</time></span> </li> <li> <a href="tracks/02-main.mp3">02. Main Theme</a> <span class="track-meta"><time datetime="PT3M45S">3:45</time></span> </li> <li data-audio-favorite> <a href="tracks/03-battle.mp3">03. Battle Theme</a> <span class="track-meta"><time datetime="PT1M58S">1:58</time></span> </li> <li> <a href="tracks/04-ending.mp3">04. Ending Theme</a> <span class="track-meta"><time datetime="PT4M12S">4:12</time></span> </li> </ol></details>Interactive Playlist (with JS)
Wrap the audio and track list in a container with class .audio-standalone to enable click-to-play behavior via the playlist utility.
<section class="audio-standalone"> <audio controls> <source src="tracks/01-opening.mp3" type="audio/mpeg"> <p><a href="tracks/01-opening.mp3" download>Download track 1</a></p> </audio> <details> <summary>Track Listing</summary> <ol class="track-list"> <li data-audio-active> <a href="tracks/01-opening.mp3">01. Opening</a> <span class="track-meta"><time datetime="PT2M14S">2:14</time></span> </li> <li> <a href="tracks/02-main.mp3">02. Main Theme</a> <span class="track-meta"><time datetime="PT3M45S">3:45</time></span> </li> </ol> </details></section>Track List Data Attributes
| Attribute | Set by | Meaning |
|---|---|---|
data-audio-active | Component + author | Currently loaded/playing track |
data-audio-played | Component | Track has been played this session |
data-audio-favorite | Author | Editorially marked as a highlight |
Text Tracks
Captions
<audio controls> <source src="podcast.mp3" type="audio/mpeg"> <track kind="captions" src="captions.vtt" srclang="en" label="English" default> <p><a href="podcast.mp3" download>Download podcast</a></p></audio>Chapters
<audio controls> <source src="podcast.mp3" type="audio/mpeg"> <track kind="chapters" src="chapters.vtt" srclang="en" label="Chapters"> <p><a href="podcast.mp3" download>Download podcast</a></p></audio>Audio Attributes
| Attribute | Description |
|---|---|
controls |
Show native playback controls (required for user interaction) |
autoplay |
Start playing automatically (discouraged — poor UX) |
muted |
Start with audio muted |
loop |
Restart audio when it ends |
preload |
none, metadata, or auto |
Preload Options
<!-- Don't preload - best for long content or many players --><audio controls preload="none">...</audio> <!-- Preload metadata only - duration, dimensions --><audio controls preload="metadata">...</audio> <!-- Preload entire file - small files, likely to play --><audio controls preload="auto">...</audio>Audio Formats
| Format | MIME Type | Support |
|---|---|---|
| MP3 | audio/mpeg | Universal — best for compatibility |
| AAC | audio/aac | Good quality, wide support |
| Ogg Vorbis | audio/ogg | Open format, Firefox/Chrome |
| Opus | audio/opus | Best quality/size ratio, modern browsers |
| WAV | audio/wav | Uncompressed, large files |
| FLAC | audio/flac | Lossless, growing support |
Accessibility
Transcripts
Provide text transcripts for audio content so deaf users and those who cannot play audio can access the information.
<figure> <audio controls> <source src="interview.mp3" type="audio/mpeg"> </audio> <figcaption> Interview with Dr. Smith about climate change. <a href="transcript.html">Read the transcript</a> </figcaption></figure>Best Practices
- Always provide a text transcript for important audio
- Never autoplay audio — it is disruptive and inaccessible
- Ensure controls are visible and keyboard accessible
- Provide context about what the audio contains
- Include duration information when available
CSS Reference
Styles defined in /src/native-elements/audio/styles.css
| Selector | Properties |
|---|---|
audio |
display: block; width: 100%; border-radius: var(--radius-m); accent-color: var(--color-primary); color-scheme: light dark; |
audio.compact |
max-width: 320px; |
audio.minimal |
height: 2.5rem; |
details:has(.track-list) |
border: 1px solid var(--color-border); border-radius: var(--radius-m); |
.track-list li[data-audio-active] |
background: color-mix(in oklch, var(--color-primary), transparent 85%); |
Related
<audio-player>— Platform web component with custom controls (Layer 4)<audio-visualizer>— Canvas visualization companion<video>— Video content with similar API<source>— Define multiple audio sources for format fallback<track>— Synchronized text tracks (captions, chapters)