Skip to content

The <waveform-playlist> element

2.1.0 adds a custom element. It is the same playlist as <div data-waveform-playlist>, as a tag — the [data-track] and [data-chapter] children are written exactly as they are inside the container:

<waveform-playlist layout="hero" show-volume continuous>
<div data-track data-url="intro.mp3" data-title="Intro" data-duration="187"></div>
<div data-track data-url="episode.mp3" data-title="Episode 42">
<div data-chapter data-time="0:00">Introduction</div>
<div data-chapter data-time="5:30">Main Topic</div>
</div>
</waveform-playlist>

Load the player and the playlist as usual (Install); the default entry registers the tag.

Every data-* option the playlist reads is an attribute, with or without the data- prefix — its own (layout, continuous, cover-size, …) and the player options it forwards (height, show-volume, waveform-style, …). When both forms are present, the plain one wins.

  • Booleans: a bare attribute means true, as HTML boolean attributes do — <waveform-playlist continuous show-volume>. (The data- form is read exactly as on a [data-waveform-playlist] container.)
  • style: plain style is the element’s CSS, so the waveform-style alias only works as data-style. Use waveform-style.
  • Not attributes: audio-mode, loop, show-loop and lazy (the playlist never forwards them to its player), and the per-track keys — url, title, artist, artwork, duration, waveform, markers, … — which belong on each [data-track].

The element renders into itself — no shadow root — so:

  • the playlist stylesheet applies as it does to a [data-waveform-playlist] container;
  • waveformplayer:* events bubble from the tag, so one listener on document hears it like any other player.

The stylesheet makes the element a block. Until the script defines it, it reserves --wp-element-height (default 90px) and keeps its raw tracks hidden, so chapter labels never flash in and out. Set the property to your playlist’s height to avoid any shift as it upgrades:

waveform-playlist { --wp-element-height: 320px; }
  • Built on connect. While the page is still parsing, it waits for DOMContentLoaded, so it reads all its tracks at once rather than building as they arrive.
  • Changing an option attribute (either form), or adding, removing or editing a [data-track] / [data-chapter] child, rebuilds the playlist — once per microtask, however many changes you make.
  • A rebuild carries on with the current track — same position, playing if it was — when that track is still in the list (the same element and URL, else the same URL). Otherwise it starts on the first track, paused.
  • Removing the element destroys its playlist. Moving it within the DOM (removed and re-added in the same task) does not, and playback carries on.
const el = document.querySelector('waveform-playlist');
// Append a track: the playlist rebuilds, and the playing track keeps playing.
el.insertAdjacentHTML('beforeend',
'<div data-track data-url="/audio/bonus.mp3" data-title="Bonus"></div>');
el.setAttribute('layout', 'list'); // rebuilt in the new layout, same track
const el = document.querySelector('waveform-playlist');
el.playlist; // the WaveformPlaylist instance (a new one after each rebuild)
el.play(); // play(), pause(), next() and previous() forward to it
el.next();
el.playlist?.seekToChapter(0, 330);

el.playlist is null before it’s built and after removal. Because a rebuild replaces the instance, read el.playlist when you need it rather than keeping a reference.

The default entry — import '@arraypress/waveform-playlist' or the CDN script — registers <waveform-playlist> (and scans for [data-waveform-playlist]), unless the page sets <html data-waveform-autoinit="false">. That opt-out switches both off.

The /no-autoinit entry registers nothing. Call defineWaveformPlaylistElement() yourself — optionally with another tag name:

import { defineWaveformPlaylistElement } from '@arraypress/waveform-playlist/no-autoinit';
defineWaveformPlaylistElement(); // <waveform-playlist>
defineWaveformPlaylistElement('my-playlist'); // or your own name

A <script> page that opted out uses the same function from the global, WaveformPlaylist.defineElement():

<html data-waveform-autoinit="false">
…
<script>WaveformPlaylist.defineElement();</script>

Either returns the registered constructor (or undefined outside a browser), and a name that is already defined is left alone. The class is exported too, as WaveformPlaylistElement.