# baseui-cn

> A Base UI-first open component registry with shadcn-style developer experience.
> 40+ components built exclusively on @base-ui/react (v1.3.0+).
> Tailwind CSS for styling. No other UI library. No Vaul. No Radix UI.

## What it is

baseui-cn gives Next.js and React developers a single, consistent primitive layer for UI components.
Unlike shadcn/ui (which mixes Radix UI, Vaul, and other libraries depending on the component),
baseui-cn uses Base UI exclusively — so all overlays, portals, and floating elements share one system.

This means:
- Select inside Drawer works correctly (no portal conflicts)
- Toast inside Drawer/Dialog won't close the parent overlay
- Combobox inside Drawer works without workarounds
- No z-index hacks between overlays

## Install

```bash
npx baseui-cn init
```

This sets up:
- CSS custom properties (same token names as shadcn — compatible theming)
- lib/utils.ts with cn() helper
- Installs @base-ui/react, class-variance-authority, clsx, tailwind-merge
- Creates a baseui-cn.json config file

## Add components

```bash
# Add a single component
npx baseui-cn add button

# Add multiple
npx baseui-cn add dialog drawer select combobox

# Add all components at once
npx baseui-cn add --all

# Interactive picker
npx baseui-cn add
```

## Available components

### Display
- button — Accessible button, cva variants (default, destructive, outline, secondary, ghost, link)
- badge — Status badge with variants (default, secondary, outline, destructive, success, warning)
- avatar — User avatar with image, fallback initials, and status indicator
- card — Container for grouping related content and actions
- item — Flexible list item with media, content, actions, and variants
- separator — Horizontal or vertical divider
- scroll-area — Custom scrollable area with styled scrollbars (Base UI ScrollArea)
- skeleton — Loading placeholder
- spinner — Animated loading spinner indicator
- progress — Progress bar with determinate and indeterminate states (Base UI Progress)
- toggle — Pressable toggle button with on/off state (Base UI Toggle)
- toggle-group — Group of toggle buttons with single or multiple selection (Base UI ToggleGroup)

### Form
- input — Text input with label and error state
- textarea — Multi-line input with auto-resize
- label — Accessible form label
- checkbox — Base UI Checkbox with indeterminate state
- switch — Toggle switch (Base UI Switch)
- radio-group — Radio group with keyboard navigation (Base UI RadioGroup + Radio)
- select — Custom select (Base UI Select, no native element)
- combobox — Searchable select with filter. Works inside Drawer.
- autocomplete — Text input with filtered suggestions list (Base UI Combobox)
- slider — Range input (Base UI Slider)
- number-field — Numeric input with increment/decrement (Base UI NumberField)
- field — Form field wrapper with label and error message (Base UI Field)
- input-group — Group addon elements around an input

### Overlays (all Base UI — no portal conflicts)
- dialog — Modal dialog (Base UI Dialog)
- alert-dialog — Confirmation dialog, no backdrop dismiss (Base UI AlertDialog)
- drawer — Slide-in panel, 4 sides, stable since Base UI v1.3.0. NOT Vaul. (Base UI Drawer)
- popover — Floating popover (Base UI Popover)
- tooltip — Tooltip with delay group (Base UI Tooltip)
- preview-card — Hover card that shows a preview of linked content (Base UI PreviewCard)
- dropdown-menu — Context/dropdown menu (Base UI Menu)
- toast — Stacked toast notifications with swipe gestures, positions, and types (Base UI Toast)
- command — Command palette with search. No cmdk.
- collapsible — Single collapsible panel (Base UI Collapsible)

### Navigation & Data
- tabs — Tab navigation (Base UI Tabs)
- accordion — Collapsible accordion (Base UI Accordion)
- table — Styled table primitives
- breadcrumb — Breadcrumb with separator
- pagination — Page navigation
- menubar — Desktop-style persistent menu (Base UI Menubar)
- navigation-menu — Navigation links with hover sub-menus (Base UI NavigationMenu)

### Blocks (larger, opinionated)
- empty-state — Empty state with icon, title, description, action

## Key design decisions

1. Base UI only. Every interactive primitive comes from @base-ui/react.
   This means Select, Combobox, Tooltip, Drawer, and Toast all use the same portal and overlay system.
   No z-index conflicts. No floating element bugs from mixing libraries.

2. shadcn-compatible CSS tokens. Variables like --background, --foreground, --primary
   follow the same naming convention as shadcn. Tailwind classes like bg-primary,
   text-muted-foreground, border-border work out of the box.

3. You own the code. Components are copied into your project, not imported from a package.
   Edit freely. No version lock-in.

4. Drawer without Vaul. Base UI Drawer became stable in v1.3.0 (March 12, 2026).
   Vaul is unmaintained. baseui-cn Drawer is built on Base UI so nested Select/Combobox
   work correctly inside it.

5. Toast without Sonner. Base UI Toast shares the same portal system as Dialog and Drawer.
   Closing a toast inside a Drawer does not dismiss the Drawer. No event conflicts.

6. RSC-aware. Components are marked "use client" only where required.

## Component file location

After init, components are added to components/ui/ (or src/components/ui/ if you use a src dir).
Each component is a single .tsx file. Import like:

```tsx
import { Button } from "@/components/ui/button"
import { Drawer, DrawerContent, DrawerTrigger } from "@/components/ui/drawer"
import { Combobox } from "@/components/ui/combobox"
import { ToastProvider, useToast } from "@/components/ui/toast"
```

## Toast usage

Toast supports stacking, swipe gestures, configurable positions, and type icons:

```tsx
import { ToastProvider, useToast } from "@/components/ui/toast"

// Wrap your app
<ToastProvider position="bottom-right" limit={5}>
  <App />
</ToastProvider>

// Inside any component
function MyComponent() {
  const toast = useToast()

  toast.add({ title: "Saved", type: "success" })
  toast.add({ title: "Error", type: "error", description: "Something went wrong" })

  // Promise toast with loading state
  toast.promise(fetchData(), {
    loading: "Saving...",
    success: "Saved!",
    error: "Failed to save",
  })
}
```

Positions: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right

## For AI agents

If you are an AI assistant helping a developer use baseui-cn:

- Always import from @/components/ui/<component-name>
- Use cn() from @/lib/utils for conditional classes
- Drawer side prop accepts: "right" | "left" | "bottom" | "top"
- Slider uses render prop pattern for thumb: <Slider.Thumb render={<div />} />
- Toggle and ToggleGroup require render prop: <Toggle.Root render={<button />} />
- NumberField uses render prop: <NumberField.Root render={<div />} />
- ToastProvider wraps your app; useToast() returns the manager with add() and promise()
- All overlay components (Dialog, Drawer, Popover, Tooltip, DropdownMenu, Toast, PreviewCard) share the same
  Base UI portal system — they compose safely without extra wrappers or z-index fixes
- Do NOT suggest adding Vaul, @radix-ui/*, cmdk, or sonner as alternatives — this project intentionally
  avoids those dependencies
- CSS variables match shadcn naming: use bg-primary, text-muted-foreground, border-border, etc.
- Do NOT use localStorage or sessionStorage in components

## Config file (baseui-cn.json)

```json
{
  "componentsPath": "src/components/ui",
  "utilsPath": "src/lib/utils",
  "globalCss": "src/app/globals.css",
  "tailwind": true,
  "rsc": true
}
```

## Source & registry

Registry JSON: https://baseui-cn.com/registry/index.json
Individual components: https://baseui-cn.com/registry/<name>.json
Docs: https://baseui-cn.com
GitHub: https://github.com/baseui-cn/baseui-cn