Quickstart: add UI sounds to your app

Add click, success, error and notification sounds to a React, Next.js or JavaScript app in under a minute with one CLI command: npx @litlab/audx init.

Requirements

• Node.js 20 or later
• A project with a package.json. Run the CLI from your app’s root, or pass --cwd <path>.
• React 18 or later, only if you use the React hooks

Set up audx

1. Run init

   npm

   npx @litlab/audx init
   

   init asks where sound files should go (src/sounds by default) and which theme to use, then:

   • writes audx.json with your choices
   • installs @litlab/audx with your package manager
   • lets you pick a starter set of sounds

   The starter set is click, toggle, select, open, close, copy, success, error and notify.

2. Play a sound

   Each sound is exported from your sounds directory. Import it and call it:

   import { click, success, error } from "@/sounds";
   
   click();
   
   try {
     await save();
     success();
   } catch {
     error();
   }
   

   The CLI picks up path aliases from tsconfig.json or jsconfig.json. Without an alias, import from a relative path such as ./src/sounds.

3. Add more sounds

   npx @litlab/audx add hover tab expand collapse
   

   Run add with no arguments to open an interactive picker, or list to browse the catalog:

   npx @litlab/audx list feedback
   

Use it in React

useSound returns a stable callback that respects <SoundProvider> and the user’s prefers-reduced-motion setting:

import { useSound } from "@litlab/audx/react";
import { click } from "@/sounds";

function SaveButton() {
  const play = useSound(click);
  return <button onClick={play}>Save</button>;
}

See Use with React to add a sound on/off setting.

Switch the theme

Every built-in theme has the same 43 sounds, so switching themes changes how your app sounds without changing your code:

npx @litlab/audx theme playful

What gets generated

src/sounds/
├── click.ts
├── success.ts
├── error.ts
└── index.ts   # re-exports every sound

Each file is a short module you own:

src/sounds/click.ts

// @audx {"theme":"minimal","sound":"click"}
// Generated by audx. Swap the whole set with `npx @litlab/audx theme <name>`.
import { defineSound } from "@litlab/audx";

export const click = defineSound({
  // ...the sound definition
});

Keep the // @audx header line. The CLI uses it to find installed sounds when you run theme, update or remove.

In a JavaScript project with no tsconfig.json, the CLI writes .js files instead.