Installation

Add Koala UI to your React app. Run the one-time setup, wire the fonts and theme into your layout, add the components you need, and pull updates later without losing your edits.

Koala UI ships owned source: the CLI copies each component into your repo under components/ui/, so you own and edit the code, no runtime dependency on us. The fastest path is the CLI; you can also copy any component by hand from its docs page.

Frameworks#

Koala UI runs wherever React 19 and Tailwind CSS v4 do. init recognizes each of these, finds the stylesheet that imports Tailwind, and wires the tokens, the fonts and the @/* alias. The theme provider is left to you (in Next.js, with next/font in the same layout), and init prints it for your framework.

  • Next.js:Recognized by init. Fonts through next/font, the theme in the root layout.
  • Vite:Recognized by init. Fonts from npm, the theme in src/main.tsx.
  • TanStack Start:Recognized by init. Fonts in src/styles.css, the theme in __root.tsx.
  • React Router:Recognized by init. Files under app/, the theme in root.tsx.
  • Astro:Recognized by init. Fonts in global.css, the theme in each React island.

In an app that renders its own <html> (Next.js, TanStack Start, React Router), the provider wraps the root layout and <html> carries suppressHydrationWarning. In Astro each React island is its own root, so each island brings its own provider.

With a coding agent#

The quickest route: hand the setup to your agent. It runs init, does every step it prints, installs the Koala UI skill so later work follows the house rules, and checks the app still builds. Run the line in your project, or paste the prompt into Cursor or any agent with a chat.

claude 'Set up Koala UI in this project. Run npx koalaui-cli@latest init and complete every next step it prints. Then run npx koalaui-cli@latest skill so you follow the Koala UI conventions from now on. Check that the app still builds, and tell me what you changed.'

Quick start#

  1. Run the setup

    init writes the design tokens to koala.css and imports them from the stylesheet that imports Tailwind (app/globals.css in Next.js, src/index.css in Vite), drops the shared helpers (cn and the tv wrapper) into lib/, adds the theme provider and installs the base dependencies. It tells the frameworks apart on its own. No account or auth needed.

    npx koalaui-cli@latest init

    On a fresh create-next-app project it replaces the starter stylesheet, whose own colors and dark media query would fight Koala’s themes. On an existing stylesheet it only adds the imports, and warns you about anything left that would override the themes: its own --background, --foreground or --radius, or a dark variant of its own. Coming from shadcn/ui? It replaces shadcn’s lib/utils.ts, and the migration guide covers the rest. Moving an app with its own components or UI kit? Migrate it one surface at a time.

  2. Wire the fonts and the theme

    Koala sets UI and body copy in Inter and headings in DM Sans, read through the --font-sans and --font-heading variables. Load both with next/font and wrap your app in the ThemeProvider that init installed. Until you do, text falls back to the system sans and only the light theme applies.

    import { Inter, DM_Sans } from "next/font/google"import { ThemeProvider } from "@/components/theme-provider"import "./globals.css"const sans = Inter({ subsets: ["latin"], variable: "--font-sans" })const heading = DM_Sans({ subsets: ["latin"], variable: "--font-heading", axes: ["opsz"] })export default function RootLayout({ children }: { children: React.ReactNode }) {  return (    <html      lang="en"      suppressHydrationWarning      className={`${sans.variable} ${heading.variable}`}    >      <body>        <ThemeProvider>{children}</ThemeProvider>      </body>    </html>  )}

    The theme follows the visitor’s OS by default. Switch it anywhere with useTheme from next-themes, which works outside Next.js too. An app with a single theme pins it instead: <ThemeProvider forcedTheme="dark">.

    "use client"import { useTheme } from "next-themes"import { Button } from "@/components/ui/button"// "light" | "cream" | "dark" | "moonlight" | "system"export function MoonlightButton() {  const { setTheme } = useTheme()  return <Button onClick={() => setTheme("moonlight")}>Moonlight</Button>}
  3. Add components

    Pass one or more component slugs. Each lands in components/ui/<name>/ (under src/ in a Vite app) with its dependencies pulled along automatically.

    npx koalaui-cli@latest add button card dialog
  4. Import and use

    Import from the path the CLI wrote to. Every component is a named export, themed through tokens, and accepts className.

    import { Button } from "@/components/ui/button"export function Example() {  return <Button>Get started</Button>}

Updating#

The code is yours, so updates never land on their own. Every install is recorded in koala.json at your project root: which version of each item you took, and a fingerprint of every file as it was written. Commit it with the rest of your code.

  1. See what changed

    On its own, diff lists the items with an update and the files you have edited. Name an item to read the line changes before you take them.

    npx koalaui-cli@latest diff button
  2. Apply the update

    Files you never touched are replaced. Files you edited are kept as they are and listed, so an update never overwrites your work. Any new dependency an update needs comes along with it.

    npx koalaui-cli@latest update

To take Koala’s version of a file you edited, merge it by hand from the diff, or run npx koalaui-cli@latest update <item> --force to replace your copy outright. init is tracked too, so the tokens in koala.css update the same way.

Pro items#

The foundation components, the lib helpers and the tokens are free. The other components, every section, the page examples and the templates are Pro and need a license key. Activate it once per machine, then add Pro items exactly like free ones.

  1. Activate your license

    Lemon Squeezy emails your key with your receipt, and keeps it in your orders. Activating claims one seat and saves the key and the seat to ~/.koalaui/config.json, readable by you only. A bad key fails here, not later.

    npx koalaui-cli@latest login 38b1460a-5104-4067-a91d-77b872934d51
  2. Add a Pro item

    Run npx koalaui-cli@latest list to see everything; Pro items are marked with a lock.

    npx koalaui-cli@latest add hero-section-3

npx koalaui-cli@latest whoami shows the active license and whether this machine is activated. npx koalaui-cli@latest logout releases the seat and forgets the key, so run it before wiping a machine or the seat stays taken.

A license covers one person. Your key is exchanged for the source on our server, so you never receive a repository token and no access is granted to your GitHub account. Every Pro file arrives stamped with a fingerprint of your license, never the key itself.

To read the source before you install it, unlock the site at /account with your key and purchase email: the Code tab of every Pro component and section then shows its files. Unlocking the site uses no seat.

A few sections link with next/link. In a Vite app add names them after it writes them: swap that import for your router’s link.

Templates#

A template is a whole site: a Next.js project with its pages, its own design layer and the Koala UI components it uses. It is Pro, and it installs into a new, empty folder rather than into a project you already have.

npx koalaui-cli@latest template pipeline-b2b my-site

The CLI writes the source, downloads the pictures from the live demo and checks each one against its checksum, then runs npm ci. Start it with npm run dev; its README says where the design variables live and what to replace before you launch. Inside it, npx koalaui-cli@latest update keeps the library files current like in any other project.

CI and agents#

Each login claims a seat, so a CI job must not run one per build. Activate one seat for CI once, from your own machine, without saving it on that machine:

npx koalaui-cli@latest login <your-key> --name ci --no-save

It prints KOALAUI_LICENSE and KOALAUI_INSTANCE. Store both as secrets in your CI and the CLI reads them from the environment. On CI, login refuses to run without --no-save. Coding agents working on your machine use your saved seat and need nothing extra.

Manual installation#

Prefer to copy by hand? Install the shared dependencies, bring the tokens over, then copy any component source straight from its docs page. Hand-copied files are not in koala.json, so the CLI’s update cannot track them.

  1. Install the dependencies

    npm install clsx tailwind-merge tailwind-variants tw-animate-css next-themes

    In a Vite app, the two faces as well:

    npm install @fontsource-variable/inter @fontsource-variable/dm-sans
  2. Copy the tokens

    The whole theme layer, color roles, radius and shadow scales, motion tokens and the custom utilities, lives in one stylesheet. Copy registry/koala.css from the repo to app/koala.css (src/styles/koala.css in Vite) and import it right after Tailwind. Without it, nothing is styled. In Vite, add the font lines from step 2 of the quick start as well.

    @import "tailwindcss";@import "./koala.css";
  3. Wire the fonts and the theme

    Copy components/theme-provider.tsx from the repo, then set up your root layout (or, in Vite, your entry file) as in step 2 of the quick start.

  4. Copy the source

    Paste a component into components/ui/<name>/ and point its imports at your project: components pull cn from lib/utils, the tv wrapper from lib/tv, and (for multi-part components) createContext from lib/create-context.

Requirements#

  • React 19: components use ref as a regular prop (no forwardRef).
  • Tailwind CSS v4: the tokens use @theme, @utility and @custom-variant, which v3 cannot read. A v3 project has to migrate first.
  • The @/* path alias: every component imports through it. Most Next.js projects already have it; a Vite app declares it twice, for TypeScript and for Vite. init adds it to a tsconfig that is plain JSON, and gives you the line for one with comments.
    {  "compilerOptions": {    "paths": {      "@/*": ["./*"]    }  }}
  • A React framework: init recognizes the five under Frameworks and wires each its own way. Any other React 19 + Tailwind v4 setup works too: it finds the stylesheet that imports Tailwind. Templates are whole Next.js sites.