Skip to content
WunderUI
General

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

Node20 or newer
React19 — Server Components supported
Tailwind CSSv4 — the CSS-first setup, no tailwind.config.js
Path alias@/* → your source root (the default in Next.js)
TypeScriptOptional, types are bundled
Tested withNext.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 .

bash
npx create-next-app@latest my-app --yes
cd my-app

Existing project

1
Add components
bash
npx wunderui-cli add button badge card

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

bash
npm install @wunderui/react

Wire up the styles

2
Import the stylesheet after Tailwind
css
/* 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

3
Import and render
tsx
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

4
Start the dev server and look
bash
node -v       # v20 or newer
npm run dev   # then open http://localhost:3000

The 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:

bash
npm create vite@latest my-app -- --template react-ts --no-interactive
cd my-app
npm install
npm install tailwindcss @tailwindcss/vite

Register the plugin and the alias, and tell TypeScript about the alias in both and :

ts
// 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") },
  },
})
json
// 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:

css
/* 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.

1
Install the package file

Download from your order, put it next to your app and install it. No Git, no build, no GitHub account.

bash
cd my-app
npm install ../wunderui-react-0.3.0.tgz   # the file from your Polar downloads
css
/* 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.

2
Optional: the source repository

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.

3
From the repository with your agent

Install the free skills in your app () and ask your agent:

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

4
From the repository by hand: build once

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.

bash
git clone https://github.com/wunder-ui/wunderui-core.git
cd wunderui-core
npm install
npm run build
cd ..
5
Install the packed library into your app
bash
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
css
/* 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:

tsx
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:

css
: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:

bash
claude mcp add wunderui -- npx -y wunderui-mcp

In Windows PowerShell, Claude Code needs the two dashes in quotes:

bash
claude mcp add wunderui '--' npx -y wunderui-mcp

Restart the editor afterwards. Then install the free agent skills for setup, screens, themes and token checks:

bash
npx skills add wunder-ui/wunderui

Your first dashboard is one sentence away — paste this into the agent:

text
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

Components render unstyled

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.

Colours are off right after create-next-app

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.

Colors look right, motion does not

You are on an older Tailwind v4 patch. The duration utilities are defined with , which needs v4 proper — not the v4 beta.

A component throws on the server

Interactive components are client components. Add to the file that imports them, or move them into one that already has it.

“command not found” right after installing Node.js

Close the terminal and open a new one, so it picks up the new PATH.

Windows: “running scripts is disabled on this system”

PowerShell blocks . Run once.

npx asks “Ok to proceed? (y)”

It downloads the tool once. Type and press Enter.

Node is too old

has to print v20 or newer. Install the LTS from nodejs.org and open a new terminal.

The GitHub invitation has not arrived

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.

The build fails after installing Core or Pro

Check Node 20+ and React 19.3 or newer, then run again. After in the checkout, build and pack again.

“Module not found: Can't resolve '@/components/ui/…'”

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.

Port 3000 is in use

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.

Where to go next