Installation
Three steps to a rendered component. The free components are source you own: one command writes them into your project, and a single stylesheet carries every token — there is no config file and no plugin. UI Blocks and the Core and Pro components come with a plan; the CLI page covers adding blocks.
New to code? Start here — a step-by-step guide from installing Node.js to a first dashboard.
Requirements
| Node | 20 or newer |
| React | 19 — Server Components supported |
| Tailwind CSS | v4 — the CSS-first setup, no tailwind.config.js |
| Path alias | @/* → your source root (the default in Next.js) |
| TypeScript | Optional, types are bundled |
| Tested with | Next.js 16 (App Router) and Vite 8, npm and pnpm |
New project
No app yet? This creates a Next.js app with TypeScript, Tailwind CSS v4, the App Router and the alias — everything WunderUI expects. Then continue with step 1 inside .
Existing project
Run it in the project root. The command writes the files into ( when the project has a folder), installs the dependencies they need with your package manager and adds . The 87 free components are MIT source, so nothing is loaded from a package at runtime and nothing changes under you. shows all of them. Core and Pro components come with a plan.
Prefer a package? It installs WunderUI Free: the same 87 free components, nothing from Core or Pro. With Core or Pro, install the full library from the private repository instead (see below).
Wire up the styles
/* app/globals.css */
@import "tailwindcss";
@import "../styles/wunderui.css";
@source "../components";The CLI does not edit this file, so add the lines yourself. The order matters: Tailwind first, WunderUI second, so the tokens land in the theme layer. The line is the one people forget — it tells Tailwind v4 to scan the component files for the utility classes they use. Without it the components render unstyled, because Tailwind never sees those class names. Adjust the relative paths to wherever your CSS file sits.
In a fresh create-next-app project, replace the whole file with these three lines: the template's own colours, dark-mode query and Arial body font would otherwise win over WunderUI's tokens.
Your first component
import { Button } from "@/components/ui/button"
import { Badge } from "@/components/ui/badge"
export default function Page() {
return (
<div className="flex items-center gap-3">
<Button variant="primary">Save changes</Button>
<Badge color="green">Active</Badge>
</div>
)
}Every component is a named export from its own file, and its page in these docs shows the props and live examples.
Check that it works
node -v # v20 or newer
npm run dev # then open http://localhost:3000The button has the indigo primary fill, white text and rounded corners, and the badge is green. A plain black-on-white button means Tailwind does not see the components: fix the path, save the CSS file and restart . should finish without errors too.
Vite
The CLI and the stylesheet work the same in a Vite + React project with Tailwind v4. Create the project and add Tailwind's Vite plugin:
Register the plugin and the alias, and tell TypeScript about the alias in both and :
// vite.config.ts
import path from "node:path"
import react from "@vitejs/plugin-react"
import tailwindcss from "@tailwindcss/vite"
import { defineConfig } from "vite"
export default defineConfig({
plugins: [react(), tailwindcss()],
resolve: {
alias: { "@": path.resolve(import.meta.dirname, "src") },
},
})// tsconfig.json and tsconfig.app.json, inside "compilerOptions"
"paths": { "@/*": ["./src/*"] }Then run . With the alias in place it writes into , so the stylesheet lines in point into the same folder:
/* src/index.css */
@import "tailwindcss";
@import "./styles/wunderui.css";
@source "./components";With Core or Pro
After checkout, Polar e-mails your receipt and license key. The full library comes as a ready-built package file, , in the downloads of your order (the e-mail and the Polar customer portal) — install it and you are done. The source repository is there too, for everyone who wants to read or change the code. Do not use here: the npm package is WunderUI Free and has none of the Core and Pro components.
Download from your order, put it next to your app and install it. No Git, no build, no GitHub account.
cd my-app
npm install ../wunderui-react-0.3.0.tgz # the file from your Polar downloads/* app/globals.css */
@import "tailwindcss";
@import "@wunderui/react/styles.css";
@source "../node_modules/@wunderui/react/dist";Then import components from and charts from . New releases: download the new file from the Polar portal and run the install again — updates are included for life.
Polar also invites the GitHub account you entered at checkout to the private repository (Pro also with the blocks, templates and skills). Accept it from the invitation e-mail or at github.com/notifications. You need it only if you want the library source or build it yourself — the steps below; you also need Git.
Install the free skills in your app () and ask your agent:
Set up WunderUI Core in this project with the wunderui-setup skill. Clone github.com/wunder-ui/wunderui-core next to this project and run npm install and npm run build in it first.The wunderui-setup skill finds the checkout next to your app, packs the library into and installs it, registers the MCP server, adds the stylesheet lines (it asks before removing a template's default colours) and renders a test page at .
Next to your app folder — one command per line, so it runs the same in PowerShell and on macOS. The first build takes about a minute. Git asks you to sign in to GitHub the first time.
git clone https://github.com/wunder-ui/wunderui-core.git
cd wunderui-core
npm install
npm run build
cd ..cd my-app
mkdir .wunderui # once — npm pack does not create it
npm pack ../wunderui-core/packages/react --pack-destination .wunderui
npm install ./.wunderui/wunderui-react-0.3.0.tgz # the file npm pack printed/* app/globals.css */
@import "tailwindcss";
@import "@wunderui/react/styles.css";
@source "../node_modules/@wunderui/react/dist";Then import components from and charts from . Your license key unlocks the code on these pages; with Pro, writes a block into your project. After , build and pack again — or install the new package file from step 1.
Dark mode
Dark mode keys off a class on an ancestor. Any theme switcher that sets the class works — with , for example, the provider handles the rest, including the system preference:
import { ThemeProvider } from "next-themes"
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
{children}
</ThemeProvider>Every color token is defined for both themes, so components switch without any work on your side.
Theming
Re-theming is a few CSS variables. Set them after the WunderUI import and every component follows — no context, no re-render, no rebuild:
:root,
.light,
.dark {
--primary: #0F9D76;
--ring: #0F9D76;
}Theming covers the brand color, dark mode, one themed section, radius, fonts and motion.
Set up your agent
WunderUI ships a machine-readable design context so a coding agent generates components that match the system instead of the defaults it was trained on. Drop DESIGN.md into your project and point your agent at it — that one file carries the tokens, the rules, the do/don't pairs and the motion recipes. The MCP server goes further and lets the agent look components up while it works. Pick your editor:
In Windows PowerShell, Claude Code needs the two dashes in quotes:
claude mcp add wunderui '--' npx -y wunderui-mcpRestart the editor afterwards. Then install the free agent skills for setup, screens, themes and token checks:
npx skills add wunder-ui/wunderuiYour first dashboard is one sentence away — paste this into the agent:
Build a revenue dashboard in app/page.tsx with four KPI cards, a monthly goal progress bar and a recent orders table. Use WunderUI (Free plan).On Free that gives KPI cards, a progress bar and a table. Charts, the Data Table and the app sidebar come with Core or Pro; with a plan, add “a line chart” to the sentence.
is the same content as data, and is the short form for smaller context windows.
If something is off
The line is missing or its path is wrong. Tailwind only generates classes it can see, so it has to point at the folder the components were written to.
The template's own , dark-mode media query and body font still sit in . Remove them, or replace the file with the three lines above.
You are on an older Tailwind v4 patch. The duration utilities are defined with , which needs v4 proper — not the v4 beta.
Interactive components are client components. Add to the file that imports them, or move them into one that already has it.
Close the terminal and open a new one, so it picks up the new PATH.
PowerShell blocks . Run once.
It downloads the tool once. Type and press Enter.
has to print v20 or newer. Install the LTS from nodejs.org and open a new terminal.
Look in your spam folder and on github.com/notifications, and check that you are signed in to the GitHub account you entered at checkout. The invitation belongs to your Polar order; your Polar e-mail links to the customer portal.
Check Node 20+ and React 19.3 or newer, then run again. After in the checkout, build and pack again.
Either that component was not added yet, or the alias is missing from (and, in Vite, from ). Run the CLI in the project root: it writes into the folder you run it from.
Next.js picks the next free port and prints it (“using available port 3001 instead”). Open that address, or stop the other server with Ctrl + C.