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 ` ` and ` ` or your router's link component. The [Vite guide](/docs/installation/vite#nextjs-specific-components) lists which components are affected.

Getting Started

Installation

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

Updated Oct 1, 2026

Cult UI components install with the shadcn CLI from the @cult-ui registry. If your project already runs shadcn/ui, skip to step 2.

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.


pnpm dlx 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:

Next.js

Vite

Without the CLI

Add a component

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


pnpm dlx 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:


pnpm dlx shadcn@latest add @cult-ui/halo-card @cult-ui/halo-input @cult-ui/halo-switch

Use it

Import from the path the CLI printed:

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:


pnpm dlx 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.

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:

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:


pnpm dlx 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:


pnpm dlx shadcn@latest add @cult-ui/halo-button --overwrite