Docs
Sounds in a few lines
Add tactile sounds to any web interface in a few lines. Every sound is synthesized in the browser, so there are no files to host.
Install
npm install @hugocxl/soundsThe package has no dependencies and works with any bundler, in plain JavaScript, React, Vue, Svelte or anything else that runs in a browser.
Play a sound
Call play with the name of a sound.
import { play } from "@hugocxl/sounds";
button.addEventListener("pointerdown", () => play("down"));
button.addEventListener("pointerup", () => play("up"));Browsers only start audio after the visitor interacts with the page, so play the first sound from an event handler such as pointerdown, click or keydown. Importing the package during server rendering is safe: nothing happens until a sound plays.
Choose the sound
| Group | Sound | Use it for |
|---|---|---|
| Press | down, up |
A button going down and coming back up |
| Press | down-primary |
The main button, a little heavier |
| Latch | latch-down, latch-up |
Checkboxes, switches and toggles |
| Selection | tick |
Sliders, wheels, tabs and segmented controls |
| Selection | blip |
A selection moving through a list or a screen |
| Typing | type, type-space, type-big, type-up |
Keys in a text field. type-big is for Enter, Backspace, Delete and Tab |
| Overlay | open |
A menu, popover or dialog opening |
| Status | success, warning, error |
The result of an action |
Haptics
If you already think in iOS haptics, call haptic instead. It plays the matching sound and vibrates on devices that support it.
import { haptic } from "@hugocxl/sounds";
haptic("selection"); // tick
haptic("medium"); // down-primary
haptic("success"); // successThe kinds are selection, light, medium, heavy, rigid, soft, success, warning and error.
Typing
Give a text field the sound of a keyboard.
import { play } from "@hugocxl/sounds";
input.addEventListener("keydown", (event) => {
if (event.repeat) return play("tick");
if (event.key === " ") play("type-space");
else if (["Enter", "Backspace", "Delete", "Tab"].includes(event.key)) play("type-big");
else if (event.key.length === 1) play("type");
});
input.addEventListener("keyup", () => play("type-up"));In React
Sounds are plain function calls, so they need no provider or hook.
import { play } from "@hugocxl/sounds";
export function SaveButton({ onSave }) {
return (
<button onPointerDown={() => play("down-primary")} onPointerUp={() => play("up")} onClick={onSave}>
Save
</button>
);
}Volume and mute
import { setEnabled, setVolume } from "@hugocxl/sounds";
setVolume(0.4); // from 0 to 1, 0.55 by default
setEnabled(false); // mute every sound, for example from a settingRespect visitors who turn sound off: keep the choice in your own settings and call setEnabled when the page loads.
Make your own
Every sound is a list of layers. A noise layer is a burst of white noise through a filter, the click. A tone layer is an oscillator gliding from freq to to, the body. Pass your own to play.
import { play, sounds } from "@hugocxl/sounds";
play({
layers: [
{ kind: "noise", freq: 3000, q: 1, level: 0.3, decay: 0.02 },
{ kind: "tone", freq: 240, to: 150, level: 0.4, decay: 0.05 },
],
});
console.log(sounds.down.layers); // start from an existing sound| Field | Layer | Meaning |
|---|---|---|
at |
both | Delay from the start of the sound, in seconds |
freq |
both | Filter frequency for noise, start pitch for a tone, in hertz |
to |
tone | End pitch, reached at the end of the decay |
filter |
noise | A biquad filter type, bandpass by default |
q |
noise | How narrow the filter is. High values ring like a spring |
wave |
tone | sine by default, or square, triangle or sawtooth |
level |
both | Peak loudness, usually below 0.5 |
attack |
tone | Seconds to reach the peak, 0.001 by default |
decay |
both | Seconds to fall to silence |
Export audio files
toWav renders any sound, without the play-to-play variation, into a WAV file. Use it for native apps, videos or design tools.
import { toWav } from "@hugocxl/sounds";
const blob = await toWav("success");The Listen page downloads every sound this way.
Credits and license
The code and the sounds are MIT licensed. The catalog grew out of a study of the interface sounds of SPEC-01, and the study notes describe what was learned from it.