> ## Documentation Index
> Fetch the complete documentation index at: https://docs.audx.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**

```bash npm theme={null}
npx @litlab/audx init
```

```bash pnpm theme={null}
pnpm dlx @litlab/audx init
```

```bash yarn theme={null}
yarn dlx @litlab/audx init
```

```bash bun theme={null}
bunx @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:

```ts theme={null}
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**

```bash theme={null}
npx @litlab/audx add hover tab expand collapse
```

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

```bash theme={null}
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:

```tsx theme={null}
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](https://docs.audx.site/guides/react.md) 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:

```bash theme={null}
npx @litlab/audx theme playful
```

## What gets generated

```text theme={null}
src/sounds/
├── click.ts
├── success.ts
├── error.ts
└── index.ts   # re-exports every sound
```

Each file is a short module you own:

```ts src/sounds/click.ts theme={null}
// @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
});
```

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.