Skip to content

Installation

Take an empty project to its first Khaeli component.

Before you start

You need a React app with Tailwind CSS v4. Registry items install with the shadcn CLI, whose own templates are Next.js, Vite, TanStack Start, React Router, Astro and Laravel. The file paths on this page are those of a Next.js app; yours follow the css path and the aliases in your components.json.

1. Run shadcn init

npx shadcn@latest init

init writes components.json, which tells the CLI where files go and which aliases they import through (@/components/ui, @/lib, @/hooks). It also adds one line to your stylesheet. Check that it is there:

app/globals.css
@import "shadcn/tailwind.css";

This step comes first because Registry items are written with the variants and utilities that file defines: data-horizontal:, data-vertical:, data-open:, data-closed:, data-checked:, no-scrollbar and the accordion keyframes. foundation does not carry them. Without the import, separators have no thickness and vertical orientations do not apply.

2. Add the @khaeli registry

Add a registries entry to the components.json that init wrote, and keep the rest of the file as it is:

components.json
{
  "registries": {
    "@khaeli": "https://ui.khaeli.com/r/{name}.json"
  }
}

Or let the CLI write the same entry:

npx shadcn@latest registry add "@khaeli=https://ui.khaeli.com/r/{name}.json"

The CLI puts an item's name in place of {name}, so @khaeli/button is fetched from https://ui.khaeli.com/r/button.json. The key and its shape hold for shadcn CLI 4.23.0, the version this Registry is built and checked with.

3. Install the foundation

npx shadcn@latest add @khaeli/foundation

Install Foundation once per app, before any component. It writes into your stylesheet:

  • the tokens: the light and dark palettes, the type scale, the radius ladder, the 30px control height and the motion durations and eases;
  • the base layer;
  • the [data-slot] rules that style every Registry component.

It also installs three packages: @fontsource-variable/inter and @fontsource-variable/geist-mono, the two font packages, and tw-animate-css.

Adding it again resets the palette in your stylesheet, so a product's own palette goes after it. Theming shows how.

4. Add a component

npx shadcn@latest add @khaeli/button

The CLI writes components/ui/button.tsx and brings what the file imports: the @khaeli/utils item and its npm packages. The Button page shows its variants, and every item's page lists what it installs with.

5. Use it

Import the component through the alias, as its own source imports other items:

app/page.tsx
import { Button } from "@/components/ui/button"

export default function Page() {
  return <Button>Create project</Button>
}

6. Wrap the app for motion

npx shadcn@latest add @khaeli/motion-provider

Animated items import m from motion/react-m and animate only inside Motion provider. Outside it they stay at their first frame, which is often invisible. The provider loads the animation features in their own chunk and follows the visitor's reduced motion setting. Put it at the root, once:

app/layout.tsx
import "./globals.css"

import { MotionProvider } from "@/components/ui/motion-provider"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <MotionProvider>{children}</MotionProvider>
      </body>
    </html>
  )
}

Next

  • The dark palette applies under a .dark class on <html>.
  • Theming: swap the palette and the font families for a product.
  • Arc: put Arc and Arc Pro items on Khaeli tokens.