Quickstart

5 min

Set Koala UI up in a React app, add your first components and render a card that follows the theme.

Before you begin

Everything on this page uses free components. They install from the public repo with no account and no key.

Set up Koala UI

  1. Run the setup

    Bash
    npx koalaui-cli@latest init

    Starter styles are replaced

    On a fresh create-next-app project, init replaces the starter stylesheet, whose colours would fight the themes. On your own stylesheet it only adds the imports and warns about overrides.

  2. Wire the fonts and the theme

    app/layout.tsxTSX
    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>  )}
  3. Add components

    Bash
    npx koalaui-cli@latest add button card dialog
  4. Render a component

    app/page.tsxTSX
    Added: import { Button } from "@/components/ui/button"Added: import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card"export default function Page() {Removed:   return <main>Hello</main>Added:   return (Added:     <main className="grid place-items-center p-6">Added:       <Card className="w-full max-w-sm">Added:         <CardHeader>Added:           <CardTitle>Koala UI is set up</CardTitle>Added:           <CardDescription>Switch the theme and this card follows.</CardDescription>Added:         </CardHeader>Added:         <CardContent>Every part reads tokens, never a raw colour.</CardContent>Added:         <CardFooter>Added:           <Button>Get started</Button>Added:         </CardFooter>Added:       </Card>Added:     </main>Added:   )}

Hand it to your agent

Bash
claude mcp add koalaui -- npx -y koalaui-cli mcpnpx koalaui-cli@latest skill

Common questions

Next steps

Your first component is on screen

Switch the theme with setTheme from next-themes and the card follows. Run diff later to see what changed upstream.