General

Installation

Four steps to a rendered component. WunderUI ships as an ESM package with a single stylesheet — there is no config file and no plugin. The components need no CLI; the CLI is only for adding UI Blocks.

Requirements

Node	20 or newer
React	19 — Server Components supported
Tailwind CSS	v4 — the CSS-first setup, no tailwind.config.js
TypeScript	Optional, types are bundled

Install

Add the package

npm install @wunderui/react

React, React DOM and Tailwind are peer dependencies — you already have them. Everything else the components need ships with the package.

Optional peers, only if you use the rich text editor

# Rich text editor components
npm install @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder

They are declared optional. Skip them and the rest of the library works untouched.

Wire up the styles

Import the stylesheet after Tailwind

/* app/globals.css */
@import "tailwindcss";
@import "@wunderui/react/styles.css";
@source "../node_modules/@wunderui/react/dist";

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 package's compiled output for the utility classes the components use. Without it the components render unstyled, because Tailwind never sees those class names. Adjust the relative path to wherever your CSS file sits.

Your first component

Import and render

import { Button, Card, StatCard } from "@wunderui/react"

export default function Page() {
  return (
    <Card className="p-6">
      <StatCard label="Revenue" value="€34,100" delta="+14.2%" trend="up" trendGood />
      <Button>Get started</Button>
    </Card>
  )
}

Every component is a named export from the package root. There is no per-component import path to remember.

Dark mode

Dark mode keys off a class on an ancestor. Wrap your app in the provider and it handles the rest, including the system preference:

import { ThemeProvider } from "@wunderui/react"

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

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, and the package's output lives outside your source tree.

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.