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:

npx shadcn@latest init

2. Add the Sona UI registry

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

{
"registries": {
  "@sona-ui": {
    "url": "https://sona-ui.vercel.app/r/{name}.json"
  }
}
}

3. Add Components

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

# 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

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).
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.