use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

Josh Comeau

Home Tutorials React

Announcing “use-sound”, a React

Hook for Sound Effects
A React Hook for Sound Effects

Maybe it's because I was an audio engineer, but I wish the web was
louder.

I know a bunch of folks will disagree, and for good reason! Sound on the
web has historically been used in annoying/awful ways:

The early web used MIDI files as background music.

Malware popups use sound effects for sinister purposes, to grab

attention and make a scam more believable.

Autoplaying videos �

However, I believe that this is the bathwater around a baby very much
worth saving. Sounds can accentuate user actions, emphasize feedback,
and add a bit of delight to an otherwise humdrum action. When done
tastefully, sound can make a product feel more tangible and real.

1 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

This isn't a new idea: video games and mobile apps use sound all the
time. In fact, the web is the odd one out; most forms of digital media I
can think of uses sound.*

When I built this blog, I wanted to experiment with this. Many UI

controls make little sounds when they're interacted with. Here's a quick
selection from this site:

Because sound is used so rarely on the web, it can be quite impactful.

It's a bit of a secret weapon, and it can make a surprisingly big difference
for the right kinds of projects!

To make it a bit easier to get started, I pulled out the hook I built for this
blog, use-sound , and published it on NPM. This tutorial gives a quick
look at what it can do, and shares additional tips and tricks for using
sound on the web.

Straight to the docs?

If you're eager to start using the hook, you can hop straight to the Github page.

Overview

use-sound is a React hook that lets you play sound effects. Here's a

2 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

typical example:

JSX

import useSound from 'use-sound';

import boopSfx from '../../sounds/boop.mp3';

const BoopButton = () => {

const [play] = useSound(boopSfx);

return <button onClick={play}>Boop!</button>;

};

It adds ~1kb (gzip) to your bundle, though it does asynchronously load a

10kb third-party dependency, Howler.

It offers a bunch of niceies out of the box, including:

Prematurely stop the sound, or pause/resume the sound.

Load an audio sprite and split it up into many individual sounds.

Tweak playback speed to speed up / slow down sounds.

Tons of event listeners.

Lots of other advanced stuff, made possible by Howler.

Check out the documentation for a comprehensive usage guide and API
reference.

3 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

Getting started

Installation
The first thing we need to do is install the package, via Yarn or NPM:

BASH

yarn add use-sound

Imports
This package exports a single default value: the useSound hook:

JS

import useSound from 'use-sound';

You'll also need to import audio files to use with this hook.

If you're using something like create-react-app /Gatsby, you should be

able to import MP3 files the same way you import other forms of media
like images:

4 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

JS

import boopSfx from '../../sounds/boop.mp3';

If you're rolling your own Webpack config, you'll want to use file-loader
to treat .mp3 files as arbitrary files.

You can also refer to paths of files put in a public or static directory.
The demos on this page, for example, point to static files kept in a
publicly-accessible folder.

Finding and prepping sounds

Installing dependencies and writing code is only half the story; we also
need to find audio samples!

My favourite resource is freesound.org. Almost all of the sound effects

used in this blog come from that resource. It's a large index of Creative
Commons Zero licensed sounds. You do need to sign up for an account
to download files, but everything is free.

Be prepared to do some digging. Many of the sounds are poorly recorded. This is
a diamond-in-the-rough, needle-in-the-haystack kind of situation.

Preparing sounds

5 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

Many of the sounds on freesound.org will need a bit of tidying up:

Like strings, sounds can be padded with empty space. You'll want to
trim it off, so that the effect is heard the moment you trigger the
sound.

You might want to tweak the volume of samples so that they're all
kept around the same level.

Sounds on freesound come in many audio formats. You may wish to

convert the sample to MP3.

To do these edits, you can use Audacity, a free, open-source, cross-

platform audio editor. Learning to use Audacity is beyond the scope of
this tutorial, but there are many amazing free resources online!

Why MP3?

Back in the day, there was no universally-supported audio format; it was

common to include an MP3, an AIFF, and a WAV, and write code to load
different files in different environments.

Happily, MP3s are supported in all mainstream browsers, including Internet

Explorer 9. They also compress very well, leading to much smaller filesizes
than lossless alternatives.

Sound and accessibility

Even as an advocate for sound on the web, I recognize that not all users
will appreciate it. And this goes beyond a subjective preference for
silence.

6 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

People who are visually impaired use a screen reader to access the web *
. Screen readers are pieces of software that parse the document and
narrate its contents as sound. If we're loading our website full of sound
effects, these sounds might clash with the narration they depend on to
make sense of our site.

For this reason, it's important to include a "mute" button somewhere on

your page, accessible by using keyboard navigation (the "Tab" key).
Ideally, no sounds should take place until the user has reached that
control in the tab order, and the value should be "sticky" so that the user
doesn't have to keep toggling it.

Conversely, deaf users will have no idea that sounds are being triggered,
as will folks who have muted their devices. For that reason, it's important
that critical information is never communicated exclusively by sound. If
you're using a sound effect to serve as confirmation for a user action, be
sure to also have a visual indication. Sites should remain 100% usable
without sound.

Recipes

Let's take a look at a few live-editable demos!

Checkbox
I find this checkbox so satisfying. If you're using a mouse, try doing a
really quick click, and then adding a bit of a delay between mouse-down
and mouse-up.

7 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

function Demo() {
const [isChecked, setIsChecked] = React.useState
false
);

const [playActive] = useSound(

'/sounds/pop-down.mp3',
{ volume: 0.25 }
);
const [playOn] = useSound(
'/sounds/pop-up-on.mp3',
{ volume: 0.25 }
);
const [playOff] = useSound(
'/sounds/pop-up-off.mp3',
{ volume: 0.25 }
);

return (
<Checkbox
name="demo-checkbox"
checked={isChecked}
size={24}
label="I agree to self-isolate"
onChange={() => setIsChecked(!isChecked)}
onMouseDown={playActive}
onMouseUp={() => {

I agree to self-isolate

8 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

Interrupting sounds
Sometimes, you only want a sound to play while the user is interacting
with it. Notice how the following sample only plays while being hovered:

function Demo() {
// For fun, try swapping out 'rising-pops' with:
// - fanfare
// - dun-dun-dun
// - guitar-loop
const soundUrl = '/sounds/rising-pops.mp3';

const [play, { stop }] = useSound(

soundUrl,
{ volume: 0.5 }
);

const [isHovering, setIsHovering] = React.useState

false
);

return (
<Button
onMouseEnter={() => {
setIsHovering(true);
play();
}}
onMouseLeave={() => {
setIsHovering(false);
stop();
}}

9 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

>

Hover over me!

Rising pitch
A fun trick I use on the "Like" button is to pitch up a sound every time it
plays. Here's how that works:

function Demo() {
const soundUrl = '/sounds/glug-a.mp3';

const [playbackRate, setPlaybackRate] = React.useSta

const [play] = useSound(soundUrl, {

playbackRate,
volume: 0.5,
});

const handleClick = () => {

setPlaybackRate(playbackRate + 0.1);
play();
};

return (
<Button onClick={handleClick}>
<span role="img" aria-label="Heart">
�
</span>
</Button>

10 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

);
}

Play/pause button
Build the next Spotify with this razzle-dazzle play/pause button.

function Demo() {
const soundUrl = '/sounds/guitar-loop.mp3';

const [play, { stop, isPlaying }] = useSound(soundUr

return (
<PlayButton
active={isPlaying}
size={60}
iconColor="var(--color-background)"
idleBackgroundColor="var(--color-text)"
activeBackgroundColor="var(--color-primary)
play={play}
stop={stop}
/>
);
}

11 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

Sprites
If your component is going to use lots of sounds, it can be worthwhile to
use an audio sprite. A sprite is an audio file with many different sounds.
By combining them into a single file, it can be a bit nicer to work with,
plus you avoid many parallel HTTP requests. *

Here we use a sprite to build a drum machine! Test it out by

clicking/tapping on the buttons, or using the numbers 1 through 4 on
your keyboard.

function Demo() {
const soundUrl = '/sounds/909-drums.mp3';

const [play] = useSound(soundUrl, {

sprite: {
kick: [0, 350],
hihat: [374, 160],
snare: [666, 290],
cowbell: [968, 200],
}
});

// Custom hook that listens for 'keydown',

// and calls the appropriate handler function.
useKeyboardBindings({

12 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

1: () => play({ id: 'kick' }),

2: () => play({ id: 'hihat' }),
3: () => play({ id: 'snare' }),
4: () => play({ id: 'cowbell' }),
})

return (
<>
<Button
aria-label="kick"
onMouseDown={() => play({ id: 'kick' })}
>

1 2 3

Sprites are covered in more detail in the API documentation

A million possibilities

The thing that strikes me about using audio on the web is that there is so
much under-explored territory. I've been experimenting with sound for a
while now, and I still feel like I'm just scratching the surface.

You've been given the tools to start experimenting, and I'd encourage
you to have some fun with this, and see where it takes you =)

You can learn more about the use-sound hook on Github.

13 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

Speaking of sound, check out what happens (on

desktop) when you mouse over that bird �.

If you enjoyed this blog post, please share it with

your network.

Share on Twitter

My latest thing

Over the past two years, I've been hard at work creating the ultimate
learning experience for React. I call it “The Joy of React”.

I've been building with React for over 8 years now, and I've learned a lot
about how to use it effectively. I absolutely love working with React; I've
tried just about every front-end framework under the sun, and nothing

14 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

makes me feel as productive as React.

In “The Joy of React”, we'll build a mental model for how React really
works, digging into concepts like we have in this tutorial. Unlike the
posts on this blog, however, my courses use a “multi-modality”
approach, mixing written content like this with video content, exercises,

A front-end web development newsletter

that sparks joy
My goal with this blog is to create helpful content for front-
end web devs, and my newsletter is no different! I'll let you
know when I publish new content, and I'll even share exclusive
newsletter-only content now and then.

No spam, unsubscribe at any time.

First Name Email

Subscribe

Josh Comeau

Tutorials Links

React Animation Twitter

CSS Career Contact

Gatsby Next.js Terms of Use

15 of 16 11/8/23, 16:08
use-sound | a React hook that lets you play sound effects https://www.joshwcomeau.com/react/announcing-use-...

Performance JavaScript Privacy Policy

© 2020-present Joshua Comeau. All Rights Reserved.

16 of 16 11/8/23, 16:08