Is @usespaceui/sounds free?

Yes. It is free and open source under the MIT license, for commercial or personal projects, with no attribution required.

How are the Sounds generated?

Each sound is generated using the Web Audio API. No external audio files like .mp3 or .wav are loaded. Nothing is stored and no network request is made.

Does it support spatial audio?

Yes. It features 3D spatial panning and tailored acoustic curves based on where the element is on the screen.

Does it make network requests?

No. Sounds are generated locally. Nothing is uploaded, sent to a remote service, or stored.

Can I use it in Vue, Solid, Svelte or vanilla JS?

Yes. Although the React component is popular, you can use HTML data-attributes in any framework.

Space UI

Documentation

A highly-optimized procedural sound engine for the web. No .mp3 or .wav files to load.@usespaceui/sounds

Overview

Everything is generated entirely in the browser using the Web Audio API with Apple device output mastering and 3D spatial panning.

1 Install

Add the package to your project. Zero dependencies. React is optional.

2 Bind

Bind interactions either via HTML data attributes, React hooks, or procedural calls.

3 Play

Enjoy 24 beautifully mastered procedural sound triggers without any network requests.

Installation

Install with your package manager of choice.

bun add @usespaceui/sounds

1. HTML Data Attributes

You can automatically bind sounds to DOM events without writing repetitive event listeners. Call bind() once in your app entry point, and then use data-space-* attributes on any element. If you leave the attribute empty, it will use its sensible default.

import { bind } from '@usespaceui/sounds'
// Call once at app startup to safely bind delegated event listeners to document
bind()

<!-- Automatically plays "tap" on click (default behavior) -->
<button data-space-click>Submit</button>
<!-- Plays a specific sound ("confirm") overriding the default -->
<button data-space-click="confirm">Save Changes</button>
<!-- Plays "tick" on mouse hover (debounced automatically) -->
<a href="#" data-space-hover>Hover me</a>
<!-- Plays "press" on pointerdown, and "release" on pointerup -->
<div data-space-press data-space-release>Press me</div>
<!-- Automatically calculates 3D spatial panning based on element position -->
<button data-space-click="sparkle" data-space-spatial>Spatial Sound</button>

Available Attributes

Defaults to tap. Listens to the click event.

Global Page Audio (Adding to <body>)

Because bind() relies on event delegation, you can add data attributes directly to your <body> element (or root layout) to enable app-wide native interactions for right-clicking, copying, and pasting:

<!-- Attach to <body> or root layout to enable app-wide native sound feedback -->
<body
  data-space-click
  data-space-contextmenu
  data-space-copy
  data-space-paste
>
  ...
</body>

AttributeDefault SoundDescription

data-space-click

tap

Plays on general clicks across elements without specific sound overrides.

data-space-contextmenu

open

Plays on every right-click context menu event anywhere on the page.

data-space-copy

copy

Plays on any native copy action (via Ctrl+C or Cmd+C).

data-space-paste

paste

Plays on any native paste action into inputs or editable areas (via Ctrl+V or Cmd+V).

2. React Hook

If you use React, the useSpaceSound hook gives you bound functions to trigger sounds and manage engine settings inside your components.

import { useSpaceSound } from '@usespaceui/sounds'
export default function Demo() {
  const { tap, confirm, slide } = useSpaceSound()
  return (
    <button
      onPointerDown={() => tap()}
      onClick={() => {
        confirm()
        slide('in')
      }}
    >
      Submit Action
    </button>
  )
}

Note for React users: You can absolutely use the HTML data attributes approach in React instead of hooks! It's often cleaner for simple buttons. Just call bind() once in a root layout or a generic Provider:

// components/SoundProvider.tsx
'use client'
import { useEffect } from 'react'
import { bind } from '@usespaceui/sounds'
export function SoundProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    bind() // Safely binds delegated event listeners to document
  }, [])
  return <>{children}</>
}

...and then in your code, you can use the data-space-* attributes directly on your React elements. Since bind() is observing the DOM globally from the Provider, all data attributes will be automatically activated.

export default function MyButton() {
  return (
    <button data-space-click="bloom" data-space-hover="tick">
      Click me
    </button>
  )
}

3. Programmatic Usage

You can also trigger sounds procedurally and adjust the engine settings globally via direct imports.

import { tap, slide, setVoice, play } from '@usespaceui/sounds'
// Set an optional global brand voice seed (alters the tonality of all sounds)
setVoice('Space UI')
// Trigger directly via dedicated functions
tap()
slide('in') // Some triggers accept parameters
// Or dynamically by name (useful for CMS or dynamic mappings)
play('slide-in', { volume: 0.8 })

4. Output Profile

The output profile adjusts the mastering EQ curve applied to all sounds. This allows you to optimize the audio output for different listening environments.

import { setOutputProfile } from '@usespaceui/sounds'
setOutputProfile('headphones')

ProfileDescription

auto

Detects the device and picks the best EQ curve automatically. (Default)

headphones

Flatter response with subtle bass lift for close-ear listening.

speakers

Compensates for typical laptop or monitor speakers.

studio

Flat, uncolored output for high-fidelity mixing environments.