Chordal docs

Install

$ npm install chordal

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

Quick start

<button data-sound-hover data-sound-click>Save</button>

import { bind } from 'chordal';

bind();

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

Attributes

Toggle: reading state at click time

data-sound-toggle is the only attribute requiring custom setup. It reads aria-pressed (or checked) at click time—wire your toggle logic first so it reads the updated state:

<button id="dark-mode-toggle" aria-pressed="false" data-sound-toggle>Dark mode</button>

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

Already have the state in your own code instead of reading it off the DOM? Call play('toggle', { state }) directly — see play().

bind(root?)

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

play(instance, options?)

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('toggle', { state: 'on' });      // already know the state? skip data-sound-toggle entirely
play('listening', { state: 'on' });   // mic session started
play('listening', { state: 'off' });  // mic session stopped

For the declarative data-sound-toggle attribute instead — reading state off the DOM at click time — see Toggle.

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();

playContinuous(action, valueRatio, options?)

For a range slider's input event, pass the current 0–1 ratio. Debounced and pitch-quantized internally, so fast dragging reads as musical steps, not a siren sweep:

<input type="range" id="volume" min="0" max="100" value="50" />

import { playContinuous } from 'chordal';

const slider = document.querySelector('#volume');
slider.addEventListener('input', () => {
  playContinuous('slider', Number(slider.value) / 100);
});

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.

SoundFamily and SoundInstance are also exported as types — the same values, at compile time — for keeping your own lookup maps honest:

import { setFamily, type SoundFamily } from 'chordal';

const familyForTheme: Record<'light' | 'dark', SoundFamily> = {
  light: 'glass-crystal',
  dark: 'metallic-tact',
};

setFamily(familyForTheme[theme]);

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.