# Installation

Sona UI is designed to be integrated into React applications through the shadcn CLI. Components are installed as source code, so they live in your project and can be customized like any other local component.

## Installation via CLI

The easiest way to use Sona UI components in your project is via the shadcn CLI. You can install components directly from our registry.

### 1. Initialize shadcn

If you haven't already, initialize shadcn in your project:

<CodeBlockWrapper code={`npx shadcn@latest init`} language="bash" />

### 2. Add the Sona UI registry

Add the Sona UI registry alias to your `components.json` file:

<CodeBlockWrapper
  code={`{
  "registries": {
    "@sona-ui": {
      "url": "https://sona-ui.vercel.app/r/{name}.json"
    }
  }
}`}
  language="json"
  filename="components.json"
/>

### 3. Add Components

You can now add Sona UI components using the `@sona-ui` alias:

<CodeBlockWrapper code={`# Add Magnetic Button
npx shadcn@latest add @sona-ui/magnetic-button

# Add Accordion

npx shadcn@latest add @sona-ui/accordion

# Add Marquee

npx shadcn@latest add @sona-ui/marquee`} language="bash" />

The CLI downloads the component source code into your configured component directory and installs the package dependencies declared by that component.

### Shared foundations

Registry components declare only the Sona foundations they use. The shadcn CLI resolves these automatically when you install from the registry:

- **sona-utils** installs `lib/sona-utils.ts`, which exports the shared `cn` helper.
- **sona-motion** installs `lib/sona-motion.ts`, which exports the shared `motionTransition` and `motionEasing` values.
- **sona-theme** applies the `sona-theme.json` registry theme, which merges optional Sona-specific tokens such as the Sona radius and danger-state colors.

Simple effects may install only `sona-utils`. Components with shared physical motion also install `sona-motion`, while components using custom Sona tokens additionally install `sona-theme`. You do not need to install the entire foundation set manually.

## Manual Installation

If you prefer not to use the CLI, you can manually copy the source code of the components from the documentation into your project.

1.  Navigate to the component documentation page (e.g., [Accordion](/docs/accordion)).
2.  Click on the "Code" tab to view the source.
3.  Copy the code into a file in your project (e.g., `components/ui/Accordion.tsx`).
4.  Copy any shared Sona foundations imported by the component, such as `lib/sona-utils.ts`, `lib/sona-motion.ts`, or the `sona-theme` tokens.
5.  Install the package dependencies listed in the component registry item.

## Dependencies

Sona UI relies on modern web technologies. Ensure your project meets the following requirements:

- **React 19** or later
- **TypeScript** (recommended)
- **Tailwind CSS 4**
- **Motion** (installed only for components that use it)
- An icon package only when required by the selected component
- **clsx** and **tailwind-merge** when the selected component uses the `sona-utils` foundation

Most of these will be handled automatically if you use the CLI.