Chordal docs

Mark up your HTML with data-sound-* attributes and call bind() once, or call play() directly whenever you need exact control.

Install

$ npm install chordal

ESM-only, zero runtime dependencies, safe to import during SSR.

Quick start

index.html
<button data-sound-hover data-sound-click>Save</button>
app.ts
import { bind } from 'chordal';

bind();

bind() scans your markup once and wires up every data-sound-* element it finds.

Attributes

AttributeFires onInstance
data-sound-hoverpointerenterhover
data-sound-clickpointerdownclick
data-sound-successclicksuccess
data-sound-errorinvaliderror
data-sound-toggleclicktoggle
data-sound-sentclicksent
data-sound-notificationclicknotification
Leave a value empty to use the active family, or set one (data-sound-click="chime") to override just that element.
Three instances have no data-sound-* attribute at all — listening and delete take a call each to start and stop or confirm, and slider is driven by playContinuous(), not a discrete DOM event. Call these directly; see the API tab.
data-sound-toggle reads on/off state from the element's own aria-pressed attribute (or a checkbox's checked property) at the moment it's clicked. Wire up your own toggle logic first, then call bind() after it, so it always reads the post-click value:
index.html
<button id="dark-mode-toggle" aria-pressed="false" data-sound-toggle>Dark mode</button>
app.ts
const toggleBtn = document.querySelector('#dark-mode-toggle');
toggleBtn.addEventListener('click', () => {
  const isOn = toggleBtn.getAttribute('aria-pressed') === 'true';
  toggleBtn.setAttribute('aria-pressed', String(!isOn));
});

bind(); // after your own toggle logic — reads aria-pressed at click time

play(instance, options?)

play(instance: SoundInstance, options?: PlayOptions): void

The direct, imperative trigger, for moments that are not a DOM interaction: an async action that just resolved, or a state your own code already knows about.

toggle and listening are stateful — pass which state just became active:

play('success', { family: 'glass-crystal' });
play('listening', { state: 'on' });   // mic session started
play('listening', { state: 'off' });  // mic session stopped

delete has no data-sound-delete attribute — call it yourself, after your own confirmation step, not on a raw click:

await confirmDelete(item);
play('delete');
item.remove();

bind(root?)

bind(root?: ParentNode): void

Scans root (defaults to document) for attributes and wires listeners. Safe to call again: already-bound elements are skipped.

playContinuous(action, valueRatio, options?)

playContinuous(action: 'slider', valueRatio: number, options?: { family?: SoundFamily }): void

For a range slider's input event, pass the current 0–1 ratio. Debounced and pitch-quantized internally.

setFamily(family) / getFamily()

The family used when a call doesn't override its own.

mute() / unmute() / isMuted()

Global on/off switch for the master output.

SOUND_FAMILIES / SOUND_INSTANCES

Exported readonly arrays for building your own picker UI.

Families

Instances

Playground

Embed <chordal-playground> for an interactive family/instance browser. It's a dev-time tool, not for production pages.

AGENTS.md

A condensed reference built for AI coding agents: install steps, the family/instance model, and the behavioral details a generated integration would otherwise get wrong.

View AGENTS.md ↗