Docs

Installation

Wingo UI components are React 19 and Tailwind CSS v4 source files that you own. The CLI copies them into your project with everything they need and remembers their versions, so updates later are one command.

Requirements

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.

Create a project

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 "@/*"

Initialize

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.

Add components

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

Browse components

Pro components

59 of the 268 items are free, including every component ported from Rare UI. 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_...

One license, one person

Create a key for each machine or agent in your account, and revoke the ones you no longer use.

Manage API keys

Dark mode and defaults

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.

Updates

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

shadcn CLI

Free items 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:

components.json

{
  "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

Answer no when shadcn asks to overwrite lib/utils.ts. 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.

Manual

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.

Coding agents

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

Set up the MCP server

Initialize

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.

Add components

npx wingo-ui@latest add button input card

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

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

Browse components

Pro components

59 of the 268 items are free, including every component ported from Rare UI. 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_...

One license, one person

Create a key for each machine or agent in your account, and revoke the ones you no longer use.

Manage API keys

Dark mode and defaults

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.

Updates

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

shadcn CLI

Free items 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:

components.json

{
  "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

Manual

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.

1Create a project

2Initialize

3Add components

4Pro components

5Dark mode and defaults

1Create a project

2Initialize

3Add components

4Pro components

5Dark mode and defaults

Create a project

Initialize

Add components

Pro components

Dark mode and defaults

Create a project

Initialize

Add components

Pro components

Dark mode and defaults