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 initbunx --bun 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:
@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:
{
"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"bunx --bun 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/foundationbunx --bun 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/buttonbunx --bun 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:
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-providerbunx --bun 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:
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>
)
}