Options & layouts

Layouts

The playlist picks one of five UIs based on content and the layout option:

1. Chapters-only — exactly one track that has chapters renders a chapters list (.wp-chapters-only) with no track row. Ideal for a single podcast episode or long-form lecture.

2. Minimal — layout: 'minimal' renders a compact row of pill buttons (.wp-controls / .wp-track-btn), one per track. Good for album switchers and tight footers.

3. List (default) — everything else renders the full track-row list (.wp-list), each row showing artwork/number, title, artist and duration, with chapters as expandable nested sub-lists under the active track.

4. Hero — layout: 'hero' (added in 1.4.0) — a “now playing” unit: the cover artwork doubles as the play/pause button beside the waveform, with a title/artist and a current/total time readout, shown over a stripped track queue. A single chaptered track instead renders a seekable chapter list with chapter markers on the waveform.

5. Grid — layout: 'grid' (added in 1.4.0) — a responsive grid of cover-art cards with a slim “now playing” transport bar (waveform + title/time) docked above or below the grid (via barPosition). The active card is ringed.

<!-- Minimal pill-button switcher -->
<div data-waveform-playlist data-layout="minimal">
  <div data-track data-url="track-1.mp3" data-title="One"></div>
  <div data-track data-url="track-2.mp3" data-title="Two"></div>
  <div data-track data-url="track-3.mp3" data-title="Three"></div>
</div>

<!-- Hero "now playing" unit over a track queue -->
<div data-waveform-playlist data-layout="hero">
  <div data-track data-url="track-1.mp3" data-title="One"   data-artist="Artist" data-artwork="1.jpg"></div>
  <div data-track data-url="track-2.mp3" data-title="Two"   data-artist="Artist" data-artwork="2.jpg"></div>
  <div data-track data-url="track-3.mp3" data-title="Three" data-artist="Artist" data-artwork="3.jpg"></div>
</div>

Playlist options

These options control the playlist itself. Set them as constructor options or as data-* on the container.

Option	data-*	Type	Default	Description
layout	data-layout	'list' | 'minimal' | 'hero' | 'grid'	'list'	UI layout. 'minimal' renders pill buttons instead of full rows; 'hero' renders a “now-playing” unit over a track queue; 'grid' renders a cover-art grid with a slim now-playing bar. The last two were added in 1.4.0.
continuous	data-continuous	boolean	false	Auto-advance to the next track when one ends. Container value reads the string 'true'.
expandChapters	data-expand-chapters	boolean	true	In multi-track lists, render each track’s chapters as a nested expandable sub-list under the active track. data-expand-chapters="false" disables.
showDuration	data-show-duration	boolean	true	Render the per-track data-duration string in the row. data-show-duration="false" disables.
showChapterMarkers	data-show-chapter-markers	boolean | null	null	Render a track’s chapters as markers on the waveform. null = smart default (see below). The attribute accepts 'true' / 'false'; absent leaves it null.
chapterMarkerColor	data-chapter-marker-color	string	'rgba(161, 161, 170, 0.85)'	Fallback colour for chapter-derived markers when a chapter has no data-color.
showPlayState	data-show-play-state	boolean	true	Show a play/pause icon overlay on the active track’s artwork (artwork tracks only). data-show-play-state="false" disables.

The following five sizing/position options were added in 1.4.0 and apply to the hero and grid layouts (plus thumbnailSize for the list layout’s row artwork):

Option	data-*	Type	Default	Description
coverSize	data-cover-size	number | null	null	Hero cover size in px. null derives a size from the waveform height ((height ?? 56) + 36).
thumbnailSize	data-thumbnail-size	number | null	null	Queue/grid/list artwork size in px. Sets the --wp-thumb-size CSS var (list & hero queue) and --wp-grid-cover (grid). null falls back to the CSS default.
density	data-density	'comfortable' | 'compact'	'comfortable'	Row spacing for the hero queue and grid. 'compact' adds .wp-density-compact for tighter rows.
coverPosition	data-cover-position	'left' | 'top'	'left'	Hero only — place the cover beside ('left') or above ('top') the waveform. 'top' adds .wp-cover-top.
barPosition	data-bar-position	'top' | 'bottom'	'bottom'	Grid only — dock the now-playing transport bar above ('top', adds .wp-now-bar-top) or below the cards.
showArtist	data-show-artist	boolean	true	Show the now-playing artist in the hero/grid bar. data-show-artist="false" hides it.

Default colour: source vs README

The runtime default for chapterMarkerColor is grey rgba(161, 161, 170, 0.85) (authoritative — the source value). Older README copy lists a purple rgba(168, 85, 247, 0.8); the source value wins at runtime.

Forwarded player options

Every core WaveformPlayer option is forwarded to the inner player — height, waveformStyle, colorPreset, barWidth, barSpacing, barRadius, buttonAlign, autoplay, showControls, showInfo, showTime, showHoverTime, showBPM, singlePlay, playOnSeek, showPlaybackSpeed, enableMediaSession, showMarkers, accessibleSeek, playbackRate, playbackRates, preload, samples, all *Color options, seekLabel, errorText, playIcon, pauseIcon, and so on. See the full player options reference.

Set them either as a constructor option or as a container data-*. The playlist inherits the player’s complete data-* contract through WaveformPlayer.utils.parseDataAttributes, so it never drifts as the player gains options.

<div data-waveform-playlist
     data-waveform-style="mirror"
     data-height="80"
     data-bar-width="3"
     data-color-preset="ocean">
  <div data-track data-url="a.mp3" data-title="A"></div>
  <div data-track data-url="b.mp3" data-title="B"></div>
</div>

Container data-* wins over constructor options

When the same option is provided both ways, the container data-* overrides the constructor option — the container’s parsed data-* surface is applied with Object.assign after the provided options are spread. For example, data-height="80" on the container beats { height: 120 } passed to the constructor.

Stripped attributes

These keys are deleted from the container’s inherited data-* surface and cannot be set at the container level — the playlist owns them and sets them per-track:

audioMode  url  title  artist  album  artwork  markers  waveform

data-audio-mode, data-url, data-title, data-artist, data-album, data-artwork, data-markers, and data-waveform on the container are ignored. The playlist always drives a self-mode player and populates the content fields from each track. (data-markers is still read on individual [data-track] elements — only the container-level key is stripped.)

Continuous playback

With continuous enabled, the playlist advances to the next track when the current one ends. This is driven by the player’s onEnd callback: it resets chapter highlighting to the start, then — if continuous is on and the current track is not the last — calls selectTrack(currentTrackIndex + 1).

const playlist = new WaveformPlaylist('#album', { continuous: true });