# Installation

Three ways in: an AI prompt, plain HTML/CSS, or React components.

## AI prompt

The quickest way: no code to install, and the AI builds the whole page in the style.

1. Open the [Studio](https://cruiseui.dev/studio) and pick a city, main colour, borders, shadows and corners.
2. Fill in your app's name and what to build.
3. Press **Copy prompt + spec** and paste it into ChatGPT, Claude, Gemini or Meta AI.

The prompt carries the full design spec, so the AI follows the same rules as these components.

Using Claude Code, Claude.ai or Codex? Install the [Cruise UI AI skill](https://cruiseui.dev/docs/ai-skill) once and just ask for Cruise UI, with no pasting.

## HTML / CSS

Works with any page or backend. One stylesheet has the tokens, dark mode and every component class.

In <head>

```
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Baloo+2:wght@400;500;600;700;800&family=Bricolage+Grotesque:opsz,wght@12..96,400;12..96,500;12..96,700&display=swap" rel="stylesheet">
<link rel="stylesheet" href="https://cruiseui.dev/theme.css">
```

`/theme.css` is always the latest. To pin this version, use `https://cruiseui.dev/theme-v1.12.css`. For Ibadan · Micra or your own colour and sizes, download a theme.css from the [Studio](https://cruiseui.dev/studio).

A whole page (save as index.html and open it)

```
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
  <link href="https://fonts.googleapis.com/css2?family=Baloo+2:wght@400;500;600;700;800&family=Bricolage+Grotesque:opsz,wght@12..96,400;12..96,500;12..96,700&display=swap" rel="stylesheet">
  <link rel="stylesheet" href="https://cruiseui.dev/theme.css">
</head>
<body style="padding: 24px">
  <span class="badge">New</span>
  <h1>Book your next ride</h1>
  <button class="brutal btn on-primary">Book a ride</button>
  <button class="brutal btn btn-secondary">See routes</button>
</body>
</html>
```

Each component page has an **HTML** tab with its markup. Dark mode: add `class="nepa-mode"` to `<html>`.

## React / Next.js

### Requirements

- React 18 or newer (tested with React 19) and Tailwind CSS v4.
- Next.js for the Navbar and Breadcrumb (they use next/link); everything else is plain React.
- The shadcn CLI. If your project doesn't use it yet, run init first:

Terminal

```
npx shadcn@latest init
```

### 1. Add the Cruise UI registry (recommended)

Add the `@cruiseui` registry to your components.json once. Components depend on each other by this name (e.g. the Combobox pulls in `@cruiseui/button` and `@cruiseui/drawer`), so set it up before adding anything.

components.json

```
{
  "registries": {
    "@cruiseui": "https://cruiseui.dev/r/{name}.json"
  }
}
```

### 2. Add components

Terminal

```
npx shadcn@latest add @cruiseui/button @cruiseui/otp-input
```

With the registry set up, a full URL works too (`npx shadcn@latest add https://cruiseui.dev/r/button.json`), but the short names are easier.

Each component brings what it needs: the theme (`app/cruise-ui.css`), `lib/cruise-utils.ts`, any other Cruise UI components it uses, and npm packages (`@base-ui/react`, `lucide-react`). Files go to `components/cruise/` and every export starts with `Cruise` (CruiseButton, CruiseOtpInput …), so nothing in `components/ui` is touched.

### 3. Turn the theme on

app/globals.css (after @import "tailwindcss")

```
@import "./cruise-ui.css";
```

app/layout.tsx

```
import { Baloo_2, Bricolage_Grotesque } from "next/font/google";
import "./globals.css";

const baloo = Baloo_2({ subsets: ["latin"], weight: ["400", "700", "800"], variable: "--font-baloo" });
const bricolage = Bricolage_Grotesque({ subsets: ["latin"], variable: "--font-bricolage" });

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={`${baloo.variable} ${bricolage.variable}`}>
      {/* "cruise" turns the theme on; add "nepa-mode" to <html> for dark mode */}
      <body className="cruise">{children}</body>
    </html>
  );
}
```

The theme only applies inside `.cruise`, so your existing shadcn/ui theme keeps working outside it. Put it on `<body>`: menus, dialogs and drawers render there. Prefer Ibadan · Micra? Add `@cruiseui/cruise-theme-ibadan` instead of the default theme.

Corners: add `data-corners="soft"` or `"round"` to `<body>`, or override `--radius`. See [Theming](https://cruiseui.dev/docs/theming).

### 4. Use it

app/page.tsx

```
import { CruiseButton } from "@/components/cruise/button";

export default function Page() {
  return <CruiseButton>Book a ride</CruiseButton>;
}
```

### With an AI assistant

The shadcn MCP server lets assistants such as Claude Code, Cursor and VS Code browse and install from registries. With the `@cruiseui` registry in components.json, ask for "the Cruise UI combobox" and it can run the add command for you. Set it up with:

Terminal

```
npx shadcn@latest mcp init --client claude
```

AI tools can also read [/llms.txt](https://cruiseui.dev/llms.txt), which lists these docs and the registry, or load the [Cruise UI AI skill](https://cruiseui.dev/docs/ai-skill), which knows to install components from the registry.