Soundz S Icon Logo

Documentation

Soundz makes it easy to wrap your UI Elements with Beautiful, Accessible, and Customizable Sound Effects.

Wrench Icon (For Installation Heading)- Installation

Install via NPM:

Rocket Icon (For Basic Usage Heading)- Basic Usage

Wrap your app in the SoundzProvider to pass global defaults, and wrap any element in Soundz to enable sounds.

providedFX="boop" can be omitted in this example since Soundz defaults to fetching "boop" if providedFX & customFX are not given.

Musical Note Icon (For Custom Sound File Heading)- Custom Sound File

You can pass an MP3 URL directly using customFX. This bypasses the providedFX fetching.

Gears Icon (For Full Example Heading)- Full Options

Here's an example using multiple props for a richer UX:

Slider Settings Icon (For Props Reference Heading)- Props Reference

providedFX

Name of predefined sound.

customFX

Custom API URL to MP3 file.

apiBaseUrl

Override the base API URL for sound fetches.

hoverFX

Sound to play on hover.

noClickSound

Disable sound on click.

fetchCooldown

Delay before re-fetching same sound (ms).

clickCooldown

Debounce clicking sound effect (ms).

keyboardKey

Trigger sound with key press.

enableHaptics

Vibrate on click if supported.

loading

Optional loading state component.

showTooltip

Show text when sound plays?

tooltipText

Text shown in tooltip.

tooltipPosition

Tooltip position preference.

tooltipAnimation

Tooltip animation preference.

animationSpeed

Animation speed.

icon

Select animated icon.

theme

Select a provided theme.

customTheme

Declare your own theme.

className

CSS class for wrapper.

style

Inline styles for wrapper.

layout

CSS layout preference.

wrap

Custom CSS class or style block.

Headphones Icon (For Provided Sounds Heading)- Provided Sounds

  • Boop → providedFX={"boop"}
  • Disable → providedFX={"disable"}
  • Drums → providedFX={"drums"}
  • DunDunDun → providedFX={"dunDunDun"}
  • Enable → providedFX={"enable"}
  • Error → providedFX={"error"}
  • Firework → providedFX={"firework"}
  • Glug → providedFX={"glug"}
  • GlugA → providedFX={"glugA"}
  • GlugB → providedFX={"glugB"}
  • Guitar → providedFX={"guitar"}
  • Meow → providedFX={"meow"}
  • Plunger → providedFX={"plunger"}
  • PlungerQuick → providedFX={"plungerQuick"}
  • Pop → providedFX={"pop"}
  • PopDouble → providedFX={"popDouble"}
  • PopHigh → providedFX={"popHigh"}
  • PopLow → providedFX={"popLow"}
  • Pops → providedFX={"pops"}
  • SwitchOff → providedFX={"switchOff"}
  • SwitchOn → providedFX={"switchOn"}
  • Tap → providedFX={"tap"}
  • Tik → providedFX={"tik"}
  • Tok → providedFX={"tok"}
  • Victory → providedFX={"victory"}
  • WaterDrip → providedFX={"waterDrip"}

Paint Palette Icon (For Themes Heading)- Themes

Soundz supports built-in themes:

  • auto (detects system light/dark)
  • light
  • dark
  • neon
  • pastel
  • mono

Universal Access Icon (For Accessibility Heading)- Accessibility

All buttons are keyboard-navigable, screen reader safe, and support haptics where available.

Box Icon (For Exported APIs Heading)- Exported APIs

  • Soundz - Main Component
  • SoundzProvider - Context Provider for defaults