Installation

Quick start#

1. 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 two frameworks apart on its own. No account or auth needed.

   npmpnpmyarnbun

   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.

2. 2

   Wire the fonts and the theme

   Next.jsVite

   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. 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.

   npmpnpmyarnbun

   npx koalaui-cli@latest add button card dialog

4. 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. 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.

   npmpnpmyarnbun

   npx koalaui-cli@latest diff button

2. 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.

   npmpnpmyarnbun

   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 sections#

Components are free, and so is one sample of every section family (the first variant on its page). Every other 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. 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.

   npmpnpmyarnbun

   npx koalaui-cli@latest login 38b1460a-5104-4067-a91d-77b872934d51

2. 2

   Add a Pro item

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

   npmpnpmyarnbun

   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 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. 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. 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. 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. 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 tells you if yours doesn’t.
  Next.jsVite

  {
    "compilerOptions": {
      "paths": {
        "@/*": ["./*"]
      }
    }
  }

• Next.js or Vite: init recognizes both and wires each its own way. Any other React 19 + Tailwind v4 setup works too: it finds the stylesheet that imports Tailwind, and the fonts follow the Vite route. Templates are whole Next.js sites.