earcons

Tiny vanilla TypeScript library for UI notification sounds — pure Web Audio API, no audio files, zero dependencies.

▶ Live demo

Why earcon?

| | earcon | Howler.js | Tone.js | ZzFX | |---|:---:|:---:|:---:|:---:| | No audio files | ✅ | ❌ | ✅ | ✅ | | Notification-specific API | ✅ | ❌ | ❌ | ❌ | | TypeScript native | ✅ | via @types | ✅ | ❌ | | Zero dependencies | ✅ | ✅ | ❌ | ✅ | | Bundle size | ~3 KB | 318 KB | 5.4 MB | <1 KB | | Semantic sound names | ✅ | ❌ | ❌ | ❌ | | Customizable | ✅ | ✅ | ✅ | ✅ |

An earcon is an auditory icon — a short, meaningful sound signal used in user interfaces. This library provides a curated set of them, generated entirely in code.

Install

npm install earcons

CDN (no build step)

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/earcons/dist/earcon.min.global.js"></script>

<!-- unpkg -->
<script src="https://unpkg.com/earcons/dist/earcon.min.global.js"></script>

All functions are available under the global Earcon object:

<button onclick="Earcon.playSuccess()">✅</button>
<button onclick="Earcon.playError()">❌</button>
<script>
  // or
  Earcon.earcon("notification", { volume: 0.8 });
</script>

Quick start

import { playSuccess, playError, playWarning } from "earcons";

// Defaults — medium variant, volume 0.5
await playSuccess();
await playError();
await playWarning();

API

Named play functions

Each function accepts an optional SoundOptions object.

import {
  playSuccess,
  playError,
  playWarning,
  playNotification,
  playClick,
  playInfo,
} from "earcons";

await playSuccess();
await playError({ variant: "long", volume: 0.8 });
await playWarning({ variant: "short" });
await playNotification({ pitch: 7 }); // +7 semitones
await playClick({ variant: "short" });
await playInfo({ volume: 0.3 });

Generic earcon() — play by name

import { earcon } from "earcons";

await earcon("success");
await earcon("error", { variant: "long" });

Built-in sound names: success · error · warning · notification · click · info

Register a custom sound

import { registerSound, earcon } from "earcons";
import type { SoundPreset } from "earcons";

const chirp: SoundPreset = (_variant, _pitch) => ({
  name: "chirp",
  duration: 0.15,
  notes: [
    { frequency: 1200, duration: 0.07, startAt: 0, waveShape: "sine" },
    { frequency: 1600, duration: 0.08, startAt: 0.07, waveShape: "sine" },
  ],
});

registerSound("chirp", chirp);
await earcon("chirp");

SoundOptions

| Option | Type | Default | Description | |---|---|---|---| | volume | number | 0.5 | Master volume, 0–1 | | variant | "short" \| "medium" \| "long" | "medium" | Duration variant | | pitch | number | 0 | Semitone offset (±) | | audioContext | AudioContext | shared singleton | Bring your own context | | onEnded | () => void | — | Called when the sound finishes |

AudioContext management

import { closeAudioContext, setAudioContext } from "earcons";

// Provide your own AudioContext (useful in frameworks)
const myCtx = new AudioContext();
setAudioContext(myCtx);

// Tear down (e.g. on unmount)
await closeAudioContext();

Sound reference

UI sounds

| Name | Waveform | Character | |---|---|---| | success | sine | Ascending major triad — bright, positive | | error | sawtooth | Descending tritone — harsh, attention-grabbing | | warning | triangle | Flat then descending minor second — cautious | | notification | sine | Soft descending two-tone ding — neutral | | click | sine | Very short transient — tactile UI feedback | | info | sine | Single soft tone — informational, non-intrusive | | toggle | triangle | Short tactile pop — on/off switch | | delete | sawtooth | Rapid descending — destructive action | | message | sine | Soft high ping — incoming chat message | | upload | sine | Ascending sweep — file sent | | download | sine | Descending sweep — file received |

Fun & misc

| Name | Waveform | Character | |---|---|---| | eightBit | square | Chiptune arpeggio — retro 8-bit 🕹️ | | police | sawtooth | Alternating wee-woo siren 🚨 | | coin | square | Classic pickup coin 🪙 | | boing | sine | Comedy spring drop 🎪 |

Browser support

Any browser that supports the Web Audio API (all modern browsers since 2014).

Autoplay policy: earcon automatically calls AudioContext.resume() before playing. Make sure you call a play function in response to a user gesture on first load, or the browser may suppress audio.

License

MIT