# Installation

pixilui installs with the shadcn CLI. You need a React 19 app with Tailwind CSS v4 and a `components.json`. If you do not have one yet, run `npx shadcn@latest init` first.

## 1. Add the registry

Add the `@pixilui` namespace to `components.json`, once per app:

```json
{
  "registries": {
    "@pixilui": "https://pixilui.com/r/{name}.json"
  }
}
```

The URL is the site's own address followed by `/r/{name}.json`. The item pages show the exact line for the site you are on.

## 2. Install an item

```bash
npx shadcn@latest add @pixilui/approval-card
```

The CLI:

- copies the item and every item it depends on into `components/pixilui/` (for the approval card: `button.tsx`, `input.tsx`, `approval-card.tsx`);
- copies the foundation: `foundation.css`, `motion-tokens.ts` and `lib/` (`utils.ts`, `use-measure.ts`, `use-morph-size.ts`);
- installs `motion`, `clsx` and `tailwind-merge`;
- adds the foundation import to your global stylesheet.

Installed files import each other with relative paths (`./button`, `./lib/utils`), so they work whatever your import alias is.

Without the namespace, you can install from the full URL. Dependencies are listed as full URLs in the registry, so they resolve too:

```bash
npx shadcn@latest add https://pixilui.com/r/approval-card.json
```

## 3. The foundation import

Every item reads the tokens in `foundation.css`. The CLI adds the import for you. If your global stylesheet does not have it, add it after Tailwind:

```css
@import "tailwindcss";
@import "../components/pixilui/foundation.css";
```

The path is relative to the stylesheet. In a Next.js app with `app/globals.css` it is `../components/pixilui/foundation.css`; in a Vite app with `src/index.css` and components in `src/components`, it is `./components/pixilui/foundation.css`.

`foundation.css` styles nothing by itself: it defines custom properties and Tailwind utilities, and adds no rules to `body`. Installing it never restyles your page.

## Next.js

Use the App Router with Tailwind v4. Items that hold state start with `"use client"`, so you can render them from server components.

Load the fonts with `next/font` and put the variables on `<html>`. The tokens look for `--font-geist-sans` (display), `--font-inter` (body) and `--font-geist-mono` (numbers and code), then fall back to the family names and the system fonts.

```tsx
import { Geist, Geist_Mono, Inter } from "next/font/google";

const geist = Geist({ variable: "--font-geist-sans", subsets: ["latin"] });
const geistMono = Geist_Mono({ variable: "--font-geist-mono", subsets: ["latin"] });
const inter = Inter({ variable: "--font-inter", subsets: ["latin"] });

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={`${geist.variable} ${geistMono.variable} ${inter.variable}`}>
      <body>{children}</body>
    </html>
  );
}
```

Then import and render:

```tsx
import { ApprovalCard } from "@/components/pixilui/approval-card";
```

## Vite

Create the app with the React and TypeScript template, add Tailwind v4 with `@tailwindcss/vite`, set the `@/*` path alias in `tsconfig.json` and `vite.config.ts`, and run `npx shadcn@latest init`. The shadcn CLI writes `components.json` with `src/components` as the target, so items land in `src/components/pixilui/`.

Fonts: load Geist, Inter and Geist Mono however you prefer (Fontsource, a `<link>` to Google Fonts, or self-hosted files) and set the variables on `:root`:

```css
:root {
  --font-geist-sans: "Geist";
  --font-inter: "Inter";
  --font-geist-mono: "Geist Mono";
}
```

## Manual copy

Every item page has a **Manual** tab that lists each file with its full source and its target path. To install by hand:

1. Copy the foundation files from the [Foundation](/components/foundation) page into `components/pixilui/`.
2. Copy the item's files, and the files of any item it depends on, to the paths shown.
3. Install the npm packages listed on the page.
4. Add the `foundation.css` import to your global stylesheet.

Keep the file names and folders as shown: the files import each other relatively.

## Updating

Run the same `add` command again. The CLI asks before overwriting a file you changed. Items are source you own, so review the diff the way you would review any other change.