# Installation

> Install Cult UI components with the shadcn CLI in Next.js, Vite, or any React project using Tailwind CSS and shadcn/ui.

Source: https://www.cult-ui.com/docs/installation

Cult UI components install with the shadcn CLI from the `@cult-ui` registry. If your project already runs shadcn/ui, skip to [step 2](#add-a-component).

### Set up shadcn/ui

Cult UI needs what `shadcn init` creates: a `components.json`, the `cn` helper in `lib/utils.ts`, an `@/` import alias, and theme tokens in your global CSS.

```bash
npx shadcn@latest init
```

Starting from scratch? `init` can scaffold the project too. Pass `-t` with `next`, `vite`, `start`, `react-router`, or `astro`, or open a framework guide:

<div className="mt-6 grid gap-4 sm:grid-cols-3">
  <LinkedCard href="/docs/installation/next">
    <p className="font-medium">Next.js</p>
  </LinkedCard>
  <LinkedCard href="/docs/installation/vite">
    <p className="font-medium">Vite</p>
  </LinkedCard>
  <LinkedCard href="/docs/installation/manual">
    <p className="font-medium">Without the CLI</p>
  </LinkedCard>
</div>

### Add a component

Use the `@cult-ui/` prefix with any component name from these docs:

```bash
npx shadcn@latest add @cult-ui/halo-button
```

The `@cult-ui` namespace is listed in the shadcn registry directory, so this works without editing `components.json`. The CLI writes the component to `components/ui/halo-button.tsx`, installs its npm dependencies, and adds any shadcn/ui components it builds on.

Add several at once:

```bash
npx shadcn@latest add @cult-ui/halo-card @cult-ui/halo-input @cult-ui/halo-switch
```

### Use it

Import from the path the CLI printed:

```tsx title="app/page.tsx"
import { HaloButton } from "@/components/ui/halo-button"

export default function Page() {
  return <HaloButton>Get started</HaloButton>
}
```

Every component page shows its props, examples, and the source you now own.

## Find components from the terminal

Search the registry and preview a component before adding it:

```bash
npx shadcn@latest search @cult-ui --query card
npx shadcn@latest view @cult-ui/prompt-composer
```

To let an AI agent do this for you, set up the [MCP Server](/docs/mcp-server).

## Pin the registry in components.json

You only need this if you use a shadcn CLI older than 3.0, run in an environment that cannot reach the shadcn registry directory, or want the registry URL to be explicit for your team:

```json title="components.json"
{
  "registries": {
    "@cult-ui": "https://www.cult-ui.com/r/{name}.json"
  }
}
```

You can also add a single component by URL with any CLI version:

```bash
npx shadcn@latest add https://www.cult-ui.com/r/halo-button.json
```

## Update a component

Components are your code, so updates are opt-in. Re-add a component with `--overwrite` to replace it with the latest version, then review the diff for any local changes you want to keep:

```bash
npx shadcn@latest add @cult-ui/halo-button --overwrite
```

## Troubleshooting

### The CLI says the @cult-ui registry is unknown

Run the latest CLI with `npx shadcn@latest`, not a globally installed or pinned older version. If it still fails, add the `registries` entry shown above to `components.json`.

### Cannot find module @/lib/utils

The project has not been initialized with shadcn/ui. Run `npx shadcn@latest init`, or follow the [manual setup](/docs/installation/manual) to add the `cn` helper and `@/` alias yourself.

### The component renders but looks unstyled or has the wrong colors

Components read shadcn theme tokens such as `--card`, `--border`, and `--muted-foreground`. Check that your global CSS defines them for both `:root` and `.dark`, and that Tailwind scans the `components` folder. See [Theming](/docs/theming).

### Cannot resolve next/image or next/link outside Next.js

A few components use Next.js image and link components. Replace them with `<img>` and `<a>` or your router's link component. The [Vite guide](/docs/installation/vite#nextjs-specific-components) lists which components are affected.