# Installation

> Set audio/ui up by hand in your framework, as the prompt of Get Started does for you.

The prompt of the [Get Started](/docs) page does this for you. Here is what it sets up by hand, in your framework.

## Prerequisites

**In React**

audio/ui is built on **React 19** and [Tailwind CSS v4](https://tailwindcss.com). Set up both first, with shadcn/ui: the [shadcn/ui installation guide](https://ui.shadcn.com/docs/installation) covers the environment.

**In Vue**

A Vue 3 app. The shadcn CLI copies the primitive into your project, and it needs one thing first: a `components.json` at the root. The file lands in `src/components/audio-ui/`, whatever alias `components.json` names. Your bundler needs that alias to build, as for any import of yours: in Vite, `resolve.alias` of `@` to `./src`. Tailwind CSS is not needed.

In Nuxt 4, the CLI writes to `components/` at the project root, not under `app/`: import from there with Nuxt's root alias, `~~/components/audio-ui/knob/vue`.

**In Svelte**

A Svelte 5 app. The shadcn CLI copies the primitive into your project, and it needs one thing first: a `components.json` at the root. The files land in `src/lib/components`. Import them through the alias of `src/lib`: `$lib` in SvelteKit before its removal, `#lib` in the latest SvelteKit (its docs say how to keep `$lib`), and in a Vite app without SvelteKit, an alias of your own: `resolve.alias` of `$lib` to `./src/lib`. Tailwind CSS is not needed.

**In Web**

A page, or an app, with a bundler such as Vite that resolves package imports. The shadcn CLI copies the primitive into your project, and it needs one thing first: a `components.json` at the root. The file lands in `src/components/audio-ui/`. It needs no Tailwind and no path alias.

With `"tsx": false` in `components.json`, the CLI writes the file as `web.js`; with `true`, as `web.ts`. Import the one you got.

**In Vue, Svelte and Web**

A minimal `components.json` is enough:

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "tsx": true,
  "tailwind": { "css": "src/style.css", "baseColor": "neutral", "cssVariables": true },
  "aliases": { "components": "@/components", "utils": "@/lib/utils" }
}
```

The shadcn-vue and shadcn-svelte CLIs install the same items, with their own prerequisites (an alias in `tsconfig.json`, and Tailwind CSS for shadcn-svelte).

## Install a primitive

**In React**

Copy a styled component with the shadcn CLI. `@audio-ui` is in shadcn's registry directory, so there is nothing to configure:

```bash
npx shadcn@latest add @audio-ui/knob
```

Or, without the styles, copy the headless primitive and style it yourself:

```bash
npx shadcn@latest add @audio-ui/knob-react
```

The same works for every item of the [Docs](/docs), including the `block-*` blocks and demos you install with `@audio-ui/…`. You can also install by manual copy, for full control.

**In Vue**

Copy the headless primitive from the address of its item, `<name>-vue.json`:

```bash
npx shadcn@latest add https://www.audio-ui.dev/r/styles/base-nova/knob-vue.json
```

It writes `components/audio-ui/knob/vue.ts` and installs what it imports: `@audio-ui/primitives`, `@audio-ui/core`, `@ui-sdk/vue` and `vue`. Every primitive installs the same way.

**In Svelte**

Copy the headless primitive from the address of its item, `<name>-svelte.json`:

```bash
npx shadcn@latest add https://www.audio-ui.dev/r/styles/base-nova/knob-svelte.json
```

It writes a component for each part in `src/lib/components/audio-ui/knob/svelte/`, with an `index.ts`, and installs what they import: `@audio-ui/primitives`, `@audio-ui/core`, `@ui-sdk/svelte` and `svelte`. Every primitive installs the same way.

**In Web**

Copy the headless primitive from the address of its item, `<name>-web.json`:

```bash
npx shadcn@latest add https://www.audio-ui.dev/r/styles/base-nova/knob-web.json
```

It writes `components/audio-ui/knob/web.ts` and installs what it imports: `@audio-ui/primitives`, `@audio-ui/core` and `@ui-sdk/web`. Every primitive installs the same way.

## Without the CLI

Each item is a JSON file at its address, and the CLI only reads it: you can do the same by hand. Open the address of the item (for the knob in Vue, `https://www.audio-ui.dev/r/styles/base-nova/knob-vue.json`), write each entry of `files` to its path under `components/audio-ui/` with its `content`, and install the packages its `dependencies` lists. An agent can do this for you: the prompt of [Get Started](/docs) says how.

## Use it

**In React**

Import it from where it landed, through your `components` alias:

```tsx
import { Knob } from "@/components/audio-ui/knob";
```

**In Vue**

Import its parts from where it landed:

```ts
import { Knob } from "@/components/audio-ui/knob/vue";
```

**In Svelte**

Import its parts from where it landed:

```ts
import { Knob } from "$lib/components/audio-ui/knob/svelte";
```

With the latest SvelteKit, write `#lib/components/audio-ui/knob/svelte`.

**In Web**

Import it once, in your app's browser entry: the import registers the `audio-ui-knob` tags, and the page can then use them.

```ts
import "./components/audio-ui/knob/web.ts";
```

The page of each component has its parts, its options and an example in your framework: [Knob](/docs/components/base/knob) is the first to open.

**In Web**

## Without a build step

A plain HTML page can run a primitive with no CLI, no bundler and no `node_modules`: the site serves each web adapter as a script, with its packages inside. Load the one you need, and write its tags:

```html title="index.html"
<script type="module" src="https://www.audio-ui.dev/web/0.1.0/knob.js"></script>

<audio-ui-knob value="40">
  <audio-ui-knob-control>
    <audio-ui-knob-track></audio-ui-knob-track>
    <audio-ui-knob-indicator></audio-ui-knob-indicator>
    <audio-ui-knob-thumb aria-label="Cutoff"></audio-ui-knob-thumb>
  </audio-ui-knob-control>
  <audio-ui-knob-value></audio-ui-knob-value>
</audio-ui-knob>
```

The folder of the address is a version, the one of `@audio-ui/primitives`, and the files of a version never change: your page keeps what you wrote it against, and moving to a newer version is a change of the address. There is no address that follows the latest release. Every primitive has a script, named as it is: `fader.js`, `meter.js`, `waveform.js`, `piano-roll.js`… A page that loads several downloads the code they share once. Browsers only run module scripts from a server, so open the page through one, not from the file system.

## The package a primitive needs

Primitives import from `@audio-ui/core` (and some components from `@audio-ui/engine`: 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/engine/time` (or `/pitch`, `/midi`, `/analysis`). Update the package:

```bash
npm install @audio-ui/core@latest
```

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

## Styling

**In React**

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](/docs/styling) for details.

**In Vue, Svelte and Web**

A primitive is headless: it brings behavior and accessibility, and no styles. Each part takes the classes and attributes of its element, and carries state attributes (`data-dragging`, `data-disabled`…) to style from, with your own CSS or with Tailwind CSS. The page of each component lists the attributes of its parts.

Continue with [First Component](/docs/first-component) to add a knob to your app.
