GitHub

Get Started

PreviousNext

A quick guide to adding your first component.

This guide provides the essentials for adding audio/ui components to your React application.

Prerequisites

Our components are built with Tailwind CSS v4. Before you begin, make sure you have a React project set up with Tailwind CSS.

Registry Configuration

Before adding components, you need to configure the registry in your components.json file.

If you don't have a components.json file yet, initialize it by running:

pnpm dlx shadcn@latest init

Then, add the registries section to your components.json file:

JSONcomponents.json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/styles/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui"
  },
  "registries": {
    "@audio": "https://audio-ui.xyz/r/{name}.json"
  }
}

The registries field allows you to configure custom registries. The {name} placeholder will be replaced with the component name when fetching from the registry.

Adding Components

You can add components automatically with the shadcn CLI or manually by copying the files.

pnpm dlx shadcn@latest add @audio/player

Step 3: Setup AudioProvider

The AudioProvider is a core component that manages the audio playback state and lifecycle for all audio components. It initializes the audio element, handles playback events, manages error retries, preloads next tracks, and synchronizes audio state with the Zustand store.

Wrap your app with AudioProvider at the root level:

// app/layout.tsx or _app.tsx
import { AudioProvider } from "@/components/audio/provider";
 
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <AudioProvider tracks={initialTracks}>{children}</AudioProvider>
      </body>
    </html>
  );
}

Step 4: Use the component

import {
  AudioPlayer,
  AudioPlayerControlBar,
  AudioPlayerPlay,
} from "@/components/audio/player";
 
export function MyAudioPlayer() {
  return (
    <AudioPlayer>
      <AudioPlayerControlBar>
        <AudioPlayerPlay />
      </AudioPlayerControlBar>
    </AudioPlayer>
  );
}

Styling

Components are styled with a design token system defined by CSS variables and implemented with Tailwind CSS. The variables follow the same approach as shadcn/ui and are fully customizable.

For detailed information about styling, color tokens, and customization options, see the shadcn/ui theming documentation.

Working with LLMs

We structure the documentation to make the components AI-friendly, so language models can understand, reason about, and modify them. To support this, we include:

  • A llms.txt file that provides a map of the documentation and component structure for your AI agent.
  • A llms-full.txt file containing an expanded view of the docs and component sources for deeper analysis.
  • A Copy Markdown button on every page, so you can easily share content or feed it to your AI workflows.

Last updated 12/4/2025

IntroductionRoadmap