Migrating from shadcn/ui

At a glance#

Where the two meet and where they part. The sections below go through each difference.

Feature	shadcn/ui	Koala UI
Foundations
Source in your repo	Included	Included
Radix primitives	Included	Included
Tailwind CSS v4	Included	Included
Variant recipes	cva	tv, with slots
Icons	Lucide	Phosphor
Theming
Themes	2	4
Accent colors	1	8
Densities	1	2
Components
Data table, date picker, combobox	Not included	Included
Rich text editor, file upload, AI chat	Not included	Included
Charts, carousel, drawer, calendar	Third-party	Built in
Beyond components
Sections	App blocks	190
Page examples	Not included	34
Templates	Not included	7
Updates that keep your edits	Not included	Included
License
Price	Free	Free and Pro

What carries over#

• The source lives in your repo under components/ui/, and the import paths stay the same: @/components/ui/button.
• Radix primitives for behavior and accessibility, asChild through Radix Slot, className merged last with cn, and a data-slot on every part.
• Named exports composed as parts: <Card><CardHeader><CardTitle>.
• Tailwind CSS v4, with theming through CSS variables.

What changes#

• tv instead of cva. Variant recipes are tailwind-variants, with slots for multi-part components, and VariantProps comes from @/lib/tv. Nothing in Koala uses class-variance-authority.
• More tokens. The color roles you know (background, foreground, primary, muted, border) are joined by brand (the accent), body for reading copy, canvas, link and status roles with a -strong text step. Four themes (light, cream, dark, moonlight) and eight accents replace one light and one dark palette. See Colors.
• The brand leads. variant="primary" is the brand color, where shadcn’s default button is near black. neutral is the black one.
• Fields have two parts. InputRoot is the frame and InputField the input, so prefixes, suffixes and buttons sit inside one border. The same goes for TextareaRoot and TextareaField.
• Components, not recipes. Data table, date picker, combobox (SelectSearch) and pagination ship as components you configure, not snippets you assemble.
• Fewer dependencies. Charts, the carousel, the drawer and the calendar are Koala’s own: no Recharts, Embla, Vaul or react-day-picker. Icons are Phosphor, not Lucide.
• Density and control size. size is sm 32, md 36 and lg 40px on every control, and a DensityProvider tightens a whole app shell at once. See Density.
• Its own CLI. koalaui-cli records installs in koala.json instead of components.json, and diff and update bring upstream changes in without overwriting the files you edited. See Installation.

Component map#

Every shadcn/ui component and where it lands. A Koala name links to its docs page, where the full API and examples live.

Variants and sizes#

The values that are named differently. Anything not listed keeps its shadcn name.

Moving a project over#

1. Clear shadcn’s colors. Delete the :root and .dark blocks shadcn added to your global stylesheet (app/globals.css, or src/index.css in Vite), and its @custom-variant dark line: they redefine --background, the other roles and --radius, and would override Koala’s themes. init warns you about each one still there.
2. Run init. It writes the tokens to koala.css (app/ in Next.js, src/styles/ in Vite), the helpers to lib/ and the theme provider. shadcn’s lib/utils.ts is replaced: Koala’s cn has the same signature, with tailwind-merge taught Koala’s tokens. If you edited yours, init keeps it and tells you what to merge.
3. Swap one component at a time. Delete shadcn’s file and add Koala’s. The import path does not change, so only the parts and props in the map above do. add refuses while a flat components/ui/<name>.tsx is still there, for the component you asked for and for every Koala component it pulls in: the import would resolve to that file instead of Koala’s folder.
4. Let the type checker find the rest. Koala’s props are typed, so a leftover shadcn prop or value fails to compile.
5. Clean up once nothing imports them: components.json, class-variance-authority, lucide-react and the packages Koala replaced.

# 1. Tokens, the lib helpers and the theme provider (after removing shadcn's color blocks)
npx koalaui-cli@latest init

# 2. One component at a time: delete shadcn's file, add Koala's
rm components/ui/button.tsx
npx koalaui-cli@latest add button

Why Koala#

• More of the product, already built. 123 components, free, including the ones you would otherwise assemble: a data table, date and range pickers, charts, a command palette, a rich text editor, file upload, and AI chat and prompt input.
• Sections, pages and templates. 190 sections for marketing, app and store pages, in families (hero, feature, pricing, FAQ, checkout and more), 34 page examples and 7 templates. One sample of every family is free; the rest is Koala UI Pro.
• Theming with range. Four themes, eight accents and a radius knob from one layer of tokens: a re-skin is a class, not a fork.
• Two densities. The same components set a spacious marketing page and a dense dashboard.
• Finish. Every component goes through the same polish pass: 40px hit areas, concentric radii, tabular numbers, reduced-motion fallbacks and AA contrast in every theme.
• Updates that keep your edits. diff and update compare against what was installed, replace the files you did not touch and list the ones you did.

FAQ#