Cuelume

Ten carefully designed interaction sounds for the web. Synthesized live with Web Audio, with no audio files and zero runtime dependencies.

Cuelume is a curated sound palette, not an audio engine. It gives buttons, links, toggles, and completed actions clear feedback without asking developers to design sounds themselves. Add an attribute, call bind(), done.

Install

npm install cuelume

Requirements

Cuelume is ESM-only. Use it through native import or an ESM-compatible bundler; CommonJS require() is not supported.

It targets modern browsers with ES modules and the Web Audio API. Server-side imports are safe, but sound playback only runs in the browser.

Quick start

Add data attributes to your markup:

<button data-cuelume-press data-cuelume-release>Save</button>
<a data-cuelume-hover="tick">Docs</a>
<button data-cuelume-toggle>Dark mode</button>

Then wire everything up once:

import { bind } from "cuelume";

bind();

Attribute	Fires on	Default sound
data-cuelume-hover	pointerenter	chime
data-cuelume-press	pointerdown	press
data-cuelume-release	pointerup	release
data-cuelume-toggle	click	toggle

Leave the attribute value empty to use the default, or set it to any sound name.

Prefer code? Play sounds imperatively:

import { play } from "cuelume";

await navigator.clipboard.writeText(text);
play("success");

Need a sound preference? Your app owns the setting; Cuelume only applies it:

import { setEnabled } from "cuelume";

setEnabled(false); // future play attempts become no-ops
setEnabled(true);  // enable playback again

Cuelume starts enabled and does not read or write storage.

Sounds

Name	Character	Suggested use
chime	Soft two-note ascending bell	Default hover
sparkle	Quick four-note twinkle	Playful accents
droplet	Single note gliding down	Dismiss, collapse
bloom	Warm slow swell	Reveal, expand
whisper	Breathy quiet swell	Dense lists
tick	Crisp instant tick	Nav and menu hover
press	Dull muted knock	Pointer down
release	Brighter springy tick	Pointer up
toggle	Mechanical click-clack	Switches, tabs
success	Warm three-note confirmation	After an action succeeds (e.g. copy to clipboard)

API

import { play, bind, setEnabled, sounds, type SoundName } from "cuelume";

• play(name?: SoundName) — play a sound immediately. Defaults to "chime".
• bind(root?: ParentNode) — delegate all data-cuelume-* interactions under root (defaults to the whole document). Idempotent and handles elements added later.
• setEnabled(enabled: boolean) — enable or disable future playback. Does not persist the preference or stop sounds already playing.
• sounds — the list of all sound names.
• SoundName — union type of the ten sound names.

Defaults that behave

• Pointer-aware. Hover, press, and release require a fine mouse pointer. Toggle follows native click activation, including keyboard and touch.
• Hover repeat guard. Hover sounds are globally throttled to one every 150ms, so sweeping across a menu stays quiet.
• One lazy AudioContext. Shared across all sounds, created on first use.
• Autoplay-friendly. Attempts to resume suspended audio without surfacing errors when a browser blocks it.
• SSR-safe. Importing on the server is a no-op.
• Safe fallback. Invalid runtime names and unavailable or blocked Web Audio make play() a silent no-op.
• Dynamic, idempotent binding. bind() never double-attaches listeners, and later DOM additions, removals, and clones work automatically.

Frameworks

Cuelume works anywhere HTML does — plain pages, Astro, React, Vue. Call bind() once after the DOM is ready. Delegated listeners keep working when components or routes replace descendants.

React:

useEffect(() => {
  bind();
}, []);

Astro (with view transitions):

import { bind } from "cuelume";

bind();

License

MIT