Tango UI

A lightweight React UI library for Next.js, powered by Tailwind CSS. Pre-compiled utilities — no Tailwind setup required for consumers.

Author: ClayW

Official Docs

🔗 https://tango-ui-new.vercel.app/

Installation

npm install tango-ui-cw

Peer Dependencies

npm install react@>=18 next@>=14 tailwind-merge@^3.6.0

next and react-dom are optional peers — only required if you use SSR/SSG features.

tailwindcss is an optional peer — not required. All Tailwind utility classes are pre-compiled and bundled in style.css. Only install it if your own project also uses Tailwind.

Quick Start

// Import components
import { Button, Input, Layout, Upload } from "tango-ui-cw";

// Import styles (required)
import "tango-ui-cw/style.css";

Compound Components

import { Button, Layout } from "tango-ui-cw";

const { MaterialButton } = Button
const { Header, Content } = Layout

// Access sub-components via dot notation
<MaterialButton>Click</MaterialButton>
<Header>...</Header>
<Content>...</Content>

// Or import directly
import { MaterialButton, Header, Content } from "tango-ui-cw";

Compatible Versions

| Package | Version | Note | |---------|---------|------| | React | >= 18 | Required | | Next.js | >= 14 | Supported | | React DOM | >= 18 | Required for SSR/SSG | | tailwind-merge | ^3.6.0 | Required | | Tailwind CSS | ^4 | Not required — utilities are pre-compiled |

Features

• Zero-config Tailwind — all utility classes are pre-compiled into the package; consumers don't need Tailwind installed
• 18+ components — Button, Input, Layout, Upload, Modal, Drawer, Table, DatePicker, ColorPicker, Search, Tooltip, Notice, Banner, Space, Line, Mark, and more
• sx prop styling — three input forms: Tailwind string, CSS shorthand object, or slot-structured object for per-slot control
• 70+ CSS shorthand properties — useTangoStyle() auto-resolves shorthand like mt, bgc, aic to full CSS properties
• Slot-based architecture — every component declares named slots, normalizeSxSlots() decomposes sx into per-slot { tw, css }
• CSS variable token system — use $primary, $border in sx values, auto-expanded to var(--primary)
• Tailwind CSS powered — mergeTwClassNames() for intelligent class conflict resolution via tailwind-merge
• Material Design variants — Button.MaterialButton with ripple effect, Input.MaterialInput with floating label
• Compound component pattern — Layout.Header, Layout.Sider, Button.MaterialButton etc., also available as named exports
• Theme customization — light/dark mode via ThemeProvider, runtime token overrides with setThemeTokens() / setThemeColor()
• 100+ CSS custom properties — oklch color space, semantic tokens for every component, responsive breakpoints
• Smooth theme transitions — automatic transition animation when switching light/dark mode
• i18n built-in — TangoI18nProvider with zh-CN / en-US packs, custom message merging, dot-path t() lookup
• Imperative notifications — useNotice() with success / fail / caution variants and auto-dismiss
• Neumorphism support — Button enu variant with soft-UI shadow effects
• Controlled & uncontrolled — Input, DatePicker, ColorPicker, Tooltip all support both patterns
• 'use client' ready — all components marked as client components, fully compatible with Next.js RSC
• forwardRef support — ref forwarding on Layout sub-components, Space, Tooltip, Notice, Upload, and more
• Data attributes — data-variant, data-size on Button for external CSS selector hooks
• Tree-shakable — ESM first with CJS fallback
• TypeScript ready — full .d.ts type declarations included and Support editor auto-inference

特性（中文）

• 零配置 Tailwind — 所有工具类已预编译打包，消费者无需安装 Tailwind
• 18+ 组件 — Button、Input、Layout、Upload、Modal、Drawer、Table、DatePicker、ColorPicker、Search、Tooltip、Notice、Banner、Space、Line、Mark 等
• sx 属性样式 — 三种输入形式：Tailwind 字符串、CSS 简写对象、或按 slot 分层的结构化对象
• 70+ CSS 简写属性 — useTangoStyle() 自动将 mt、bgc、aic 等简写解析为完整 CSS 属性
• Slot 架构 — 每个组件声明命名 slot，normalizeSxSlots() 将 sx 分解为每个 slot 的 { tw, css }
• CSS 变量 Token 系统 — 在 sx 值中使用 $primary、$border，自动展开为 var(--primary)
• Tailwind CSS 驱动 — mergeTwClassNames() 基于 tailwind-merge 智能解决类名冲突
• Material Design 变体 — Button.MaterialButton 带涟漪效果，Input.MaterialInput 带浮动标签
• 复合组件模式 — Layout.Header、Layout.Sider、Button.MaterialButton 等，同时支持命名导出
• 主题定制 — 通过 ThemeProvider 切换亮/暗模式，setThemeTokens() / setThemeColor() 运行时覆盖 token
• 100+ CSS 自定义属性 — oklch 色彩空间，每个组件的语义化 token，响应式断点
• 平滑主题过渡 — 切换亮/暗模式时自动播放过渡动画
• 内置国际化 — TangoI18nProvider 支持 zh-CN / en-US 语言包，自定义消息合并，点路径 t() 查找
• 命令式通知 — useNotice() 提供 success / fail / caution 变体，支持自动消失
• 拟物风支持 — Button enu 变体带柔和 UI 阴影效果
• 受控与非受控 — Input、DatePicker、ColorPicker、Tooltip 均支持两种模式
• 'use client' 就绪 — 所有组件标记为客户端组件，完全兼容 Next.js RSC
• forwardRef 支持 — Layout 子组件、Space、Tooltip、Notice、Upload 等支持 ref 转发
• Data 属性 — Button 上的 data-variant、data-size 可用于外部 CSS 选择器
• 可 Tree-shaking — ESM 优先，同时提供 CJS 回退
• TypeScript 就绪 — 包含完整的 .d.ts 类型声明，支持编辑器自动推断

License

MIT