cuelume

Cuelume

Seventeen 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:

Save
Docs
Dark mode
Launch

Then wire everything up once:

import { bind } from "cuelume";

bind();

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");
play("success", { volume: 0.4 }); // quieter for this play only

Need sound preferences? Your app owns the settings; Cuelume only applies them:

import { setEnabled, setVolume } from "cuelume";

setVolume(0.7);    // global multiplier, clamped to 0–1
setEnabled(false); // future play attempts become no-ops
setEnabled(true);  // enable playback again

Cuelume starts enabled at full volume and does not read or write storage.

Sounds

API

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

• play(name?: SoundName, options?: { volume?: number }) — play a sound immediately. Defaults to "chime"; options.volume controls this play only.
• 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.
• setVolume(volume: number) — set the global volume for future playback, clamped to 0–1. Non-finite values are ignored and preferences are not persisted.
• sounds — the list of all sound names.
• SoundName — union type of the seventeen sound names.

Defaults that behave

• Pointer-aware. Hover requires a fine mouse pointer. Press and release support mouse, touch, and pen; toggle follows native click activation, including keyboard.
• Hover repeat guard. Hover sounds are globally throttled to one every 150ms, so sweeping across a menu stays quiet.
• Audible without clipping. One shared boosted output stage keeps sounds clear, with native compression protecting overlapping cues.
• 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, play } from "cuelume";

bind();
document.addEventListener("astro:page-load", () => play("arrival"));

Browsers block audio on a fresh visit until the user interacts with the page. The arrival cue therefore plays on client-side navigations after that first interaction.

License

MIT