Installation

• React 19 with Next.js (App Router or Pages) or Vite.
• Tailwind CSS v4 and TypeScript, with the @/* import alias.
• Node.js 20.19 or newer for the CLI.

Skip this step in an existing project that already uses Tailwind CSS v4.

npx create-next-app@latest my-app --ts --tailwind --eslint --app --import-alias "@/*"

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install tailwindcss @tailwindcss/vite
npm install -D @types/node

// vite.config.ts
import path from "node:path"
import tailwindcss from "@tailwindcss/vite"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: { alias: { "@": path.resolve(__dirname, "./src") } },
})

npx wingo-ui@latest init

• Detects the framework, the @/* alias and your global stylesheet.
• Installs clsx and tailwind-merge and creates lib/utils.ts with the cn helper.
• Merges the design tokens (colors, radius, elevation, motion) into the stylesheet, without touching values you already have.
• Writes wingo-ui.json. Commit it, together with the .wingo-ui/ folder the CLI keeps for safe updates.

pnpm, yarn and bun work too: pnpm dlx wingo-ui@latest init, yarn dlx wingo-ui@latest init, bunx wingo-ui@latest init.

npx wingo-ui@latest add button input card

Files land in components/ui, components/blocks, hooks and lib. Shared helpers (like lib/motion or use-controllable-state) and npm packages come along automatically. Each component page shows its install command, props and examples.

import { Button } from "@/components/ui/button"

export function Save() {
  return <Button tone="brand">Save changes</Button>
}

75 of the 374 components, blocks and hooks are free, including the animated showcase components and the everyday basics. The others need a Pro plan. Sign the CLI in once per machine:

npx wingo-ui@latest login

It opens the browser to approve the device and stores an API key in ~/.config/wingo-ui. On servers and in CI, pass a key from your account instead, or set WINGO_UI_API_KEY:

npx wingo-ui@latest login --key wui_...
# or
export WINGO_UI_API_KEY=wui_...

Components follow the .dark class. With Next.js, next-themes sets it. UIProvider (installed with every component) sets app-wide defaults for any component and the locale for dates and numbers; explicit props always win.

npm install next-themes

// app/layout.tsx
import { ThemeProvider } from "next-themes"
import { UIProvider } from "@/lib/ui-config"
import "./globals.css"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
          <UIProvider locale="en-US" defaults={{ button: { radius: "full" } }}>
            {children}
          </UIProvider>
        </ThemeProvider>
      </body>
    </html>
  )
}

Want your own colors, radius and font? Build a theme in the theme generator and apply it with npx wingo-ui@latest theme apply theme.json.

Every release lists what changed in the changelog. The CLI compares your project with the latest release and merges upstream changes into your copies, keeping your own edits (a three-way merge; real conflicts get markers like a git merge).

npx wingo-ui@latest outdated      # what changed upstream
npx wingo-ui@latest diff button   # see the changes
npx wingo-ui@latest update        # update everything, or name items

First add the theme: the Wingo UI tokens a shadcn theme lacks (brand and status colors, surfaces, elevation, layers and motion). It adds them to your global CSS and keeps every variable you already have. Each item pulls it in too.

npx shadcn@latest add https://wingo-ui.com/r/theme.json

Free items then install straight from their URL in any project set up with shadcn:

npx shadcn@latest add https://wingo-ui.com/r/button.json

For Pro items, add the @wingo-ui registry with your API key to components.json, put WINGO_UI_API_KEY in .env.local, and install by name:

{
  "registries": {
    "@wingo-ui": {
      "url": "https://wingo-ui.com/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${WINGO_UI_API_KEY}"
      }
    }
  }
}

npx shadcn@latest add @wingo-ui/calendar

The components use your project's own cn from lib/utils.ts, so shadcn never asks to overwrite it. Without a Pro key, a Pro item stops with a link to the pricing page. Projects created with a Base UI style rewrite asChild, which the components rely on; use the Wingo UI CLI there. The shadcn CLI does not record versions, so wingo-ui update cannot merge later changes into those files.

• Copy the files from the component's Code tab (Pro items need a Pro plan) into the same paths in your project.
• Install the npm packages listed under Dependencies, and add the Wingo UI items it depends on.
• Add lib/utils.ts and the tokens: the MCP tool get_theme_tokens and the theme generator both give you the CSS.

Connect Claude Code, Codex, Gemini CLI, Grok or Cursor to the MCP server. Your agent then searches the library before it writes UI, reads props and design rules, installs with the CLI and checks your components for updates.

npx wingo-ui@latest agents install

• Next.js and Tailwind CSS

  Tailwind v4 Nextjs 16 Setup: Config, Fonts and 5 Fixes

  Set up a Tailwind v4 Nextjs 16 app: PostCSS plugin or the new Turbopack loader, @theme tokens in CSS, next/font variables and fixes for five errors.

  Nov 6, 2026 · 9 min read

• Next.js and Tailwind CSS

  Next.js Component Library Setup for the App Router

  Next.js component library setup for the App Router, tested on Next.js 16.4: use client boundaries, tokens in globals.css, dark mode without a flash, updates.

  Oct 13, 2026 · 8 min read

• Next.js and Tailwind CSS

  shadcn Vite Setup with Tailwind CSS v4 and React 19

  shadcn Vite setup tested on Vite 8 and TypeScript 6: the Tailwind v4 plugin, the @ alias in tsconfig.app.json, dark mode without Next.js, then add components.

  Oct 13, 2026 · 7 min read