Skip to content

The <waveform-sounds> element

2.1.0 adds a custom element, modelled on the core’s <waveform-player>. It is the same list as <div data-waveform-sounds>, as a tag:

<waveform-sounds manifest="/previews/sounds.json" page-size="20"></waveform-sounds>

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

Every data-* option is an attribute, with or without the data- prefix: manifest, player, page-size, filters, columns, url-state, auto-advance, strings, player-options, … When both forms are present, the plain one wins.

  • Booleans: a bare attribute means true — <waveform-sounds auto-advance>, as data-auto-advance is.
  • Values are parsed exactly as data-* values are: lists are comma-separated (filters="type,bpm"), and strings / player-options take JSON.
<waveform-sounds manifest="/previews/sounds.json" player="strip"
filters="type,bpm" columns="bpm,key" url-state></waveform-sounds>

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

  • the stylesheet applies, as to any [data-waveform-sounds] (its rules name the tag as well as the class);
  • waveformsounds:* events bubble from the tag, so one listener on document hears it like any other list.

The stylesheet makes the element a block. An empty element that isn’t defined yet (its manifest still to load) holds --ws-element-height if you set one (default 0), so the page doesn’t shift as it fills in.

Put renderSounds() output inside the tag and the element adopts it, as [data-waveform-sounds] does: the list is there, readable and crawlable, before any script runs, and the runtime wires it up instead of rebuilding it.

import { renderSounds } from '@arraypress/waveform-sounds/render';
const html = `<waveform-sounds page-size="20">${renderSounds(sounds, { pageSize: 20 })}</waveform-sounds>`;

The runtime reads its options from the element’s attributes, not from the markup — give the tag the same options you gave the renderer (see Server rendering).

When the element is removed, the list is destroyed with destroy({ restore: true }): adopted markup is put back exactly as the server sent it, so the same markup can be mounted again. Do the same when you tear down a list built in script over server markup that a framework will re-mount:

list.destroy({ restore: true }); // adopted markup back as it arrived
  • Built on connect, adopting any server markup inside it, or fetching its manifest.
  • Changing an option attribute (either form) rebuilds the list once per microtask, from the sounds it already holds — or fetches afresh when manifest changed.
  • Removing the element destroys its list. Moving it within the DOM (removed and re-added in the same task) does not, and playback carries on.
const el = document.querySelector('waveform-sounds');
el.sounds; // the WaveformSounds instance (null while disconnected)
await el.sounds?.ready;
el.sounds?.setFilter({ type: 'Bass' });
el.setAttribute('page-size', '50'); // rebuilt with the new page size

A rebuild makes a new instance, so read el.sounds when you need it rather than keeping a reference.

The default entry — import '@arraypress/waveform-sounds' or the CDN script — registers <waveform-sounds> before it scans the page, unless the page sets <html data-waveform-autoinit="false">. That opt-out switches both off.

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

import { defineWaveformSoundsElement } from '@arraypress/waveform-sounds/no-autoinit';
defineWaveformSoundsElement(); // <waveform-sounds>
defineWaveformSoundsElement('pack-sounds'); // or your own name

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

<html data-waveform-autoinit="false">
…
<script>WaveformSounds.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 WaveformSoundsElement.