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.

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

Install

Add components

npx wunderui-cli add button badge card

The command writes the files into , installs the dependencies they need and adds . The 76 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.

Wire up the styles

Import the stylesheet after Tailwind

/* app/globals.css */
@import "tailwindcss";
@import "../styles/wunderui.css";
@source "../components";

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.

Your first component

Import and render

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.

With Core or Pro

After checkout, Polar e-mails your receipt and license key and invites your GitHub account to the private repository (Pro also ). Accept the invitation, build the package once and install a packed copy into your app:

git clone https://github.com/wunder-ui/wunderui-core.git
cd wunderui-core && npm install && npm run build

# in your app
mkdir .wunderui   # once — npm pack does not create it
npm pack ../wunderui-core/packages/react --pack-destination .wunderui
npm install ./.wunderui/wunderui-react-<version>.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 . Your license key unlocks the code on these pages; with Pro, writes a block into your project. After , build and pack again.

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.

claude mcp add wunderui -- npx -y wunderui-mcp
npx skills add wunder-ui/wunderui

The first command connects the MCP server to Claude Code; the second installs the free agent skills for setup, screens, themes and token checks.

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.

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.