Quickstart
Set Koala UI up in a React app, add your first components and render a card that follows the theme.
Before you begin
- React 19. Components take
refas a regular prop, with noforwardRef. - Tailwind CSS v4. The tokens use
@theme,@utilityand@custom-variant. - The
@/*path alias.initadds it to a plain JSON tsconfig and tells you if it is missing.
Everything on this page uses free components. They install from the public repo with no account and no key.
Set up Koala UI
Run the setup
initwrites the tokens tokoala.css, imports them from the stylesheet that imports Tailwind, addslib/utils.ts,lib/tv.tsand the theme provider, and installs the base packages.Bashnpx koalaui-cli@latest initStarter 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.
Wire the fonts and the theme
Koala sets UI and body copy in Inter and headings in DM Sans, through
--font-sansand--font-heading. Wrap your app in theThemeProviderthat init installed.Add components
Pass one or more names. Each lands in
components/ui/<name>/with the components and helpers it imports, and the packages it needs are installed.Bashnpx koalaui-cli@latest add button card dialogRender a component
Import from the path the CLI wrote to. Every part is a named export and accepts
className.app/page.tsxTSXAdded: 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
Register the MCP server once and your coding agent can search, read and install Koala on its own, running init first in a project that has no setup.
claude mcp add koalaui -- npx -y koalaui-cli mcp
npx koalaui-cli@latest skillCommon 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.