Installation

This guide shows how to add audio/ui to a shadcn project. If you do not use shadcn/ui, install the headless primitives with npm install @audio-ui/react instead, see the Introduction.

Prerequisites

audio/ui is built on React 19 and Tailwind CSS v4. Set up both first. The shadcn/ui installation guide covers the environment.

Setup the audio/ui Registry

Add the audio/ui registry namespace to your components.json and set your component library and style. See the shadcn registry docs for the registry config.

Copy
{
  "registries": {
    "@audio-ui": "https://www.audio-ui.dev/r/{style}/{name}.json"
  }
}

Components

You can install audio/ui using the shadcn CLI for automation or by manual installation for full control. Both methods apply to everything in Docs and the component catalog, including the block-* blocks and demos you install with @audio-ui/….

The package a component needs

Some components import from @audio-ui/core (pitch, MIDI, musical time, analysis). Installing one adds the package to your package.json if it is not there, with no version pinned: the version is yours to choose.

The CLI leaves a version you already have. If an older @audio-ui/core is installed and a component needs a subpath it did not have yet, your build says it cannot resolve @audio-ui/core/time (or /pitch, /midi, /analysis). Update the package:

bunnpmpnpmyarn
Copy
pnpm add @audio-ui/core@latest

If your package manager still resolves the old version, bypass its cache: with Bun, add --no-cache.

Styling

Components are styled with a design token system defined by CSS variables and implemented with Tailwind CSS, following the same conventions as shadcn/ui so they're fully customizable. See the Styling guide for details.

Work with an AI agent

audio/ui is designed to be used by AI coding agents.

• Agent skill: npx skills add ouestlabs/audio-ui teaches your agent which layer to pick and how to install and wire each component.
• MCP server: connect https://www.audio-ui.dev/mcp so your agent can list components, read their docs and search the catalog.
• llms.txt: a structured map of the documentation. Every docs page is also served as markdown.
• Copy Markdown: every page has a button to feed its content to your agent.

Next Steps

Head over to the Knob docs to install your first component, or browse the component catalog for ready-to-use blocks.