## 59+ Components, Zero Lock-In

Duck UI is a component library on top of the GentleDuck ecosystem. Over 59
production-ready components covering forms, navigation, data display, overlays, and
layout.

Unlike most component libraries, Duck UI doesn't install as a dependency. The CLI
**copies source code directly into your project**. You own every line — read it,
modify it, delete parts you don't need, and never worry about a breaking upstream
update.

***

## The Component Catalog

### Form Components

| Component | Description |
| --- | --- |
| **Button** | Customizable action trigger with 6 variants and 5 sizes |
| **Button Group** | Grouped buttons with shared separators |
| **Input** | Text input with label, description, and error states |
| **Input Group** | Compound input with prefix/suffix addons |
| **Input OTP** | One-time password input with configurable length |
| **Textarea** | Multi-line text input |
| **Checkbox** | Binary toggle with indeterminate state |
| **Radio Group** | Single-selection from a set |
| **Select** | Dropdown selection with search and groups |
| **Combobox** | Searchable select with keyboard navigation |
| **Switch** | Toggle switch with motion |
| **Slider** | Range input with min/max/step |
| **Calendar** | Date picker grid |
| **Date Picker** | Calendar with popover |
| **Label** | Accessible form label |
| **Field** | Form field wrapper with label + description + error |
| **React Hook Form** | Pre-wired form primitives for react-hook-form |
| **JSON Editor** | Structured JSON editing with validation |

### Navigation

| Component | Description |
| --- | --- |
| **Command** | Command palette with fuzzy search |
| **Navigation Menu** | Multi-level navigation with flyout panels |
| **Breadcrumb** | Path navigation with separator customization |
| **Menubar** | Application menu bar |
| **Tabs** | Tabbed content navigation |
| **Pagination** | Page navigation controls |

### Data Display

| Component | Description |
| --- | --- |
| **Table** | Data table with sorting, filtering, and selection |
| **Data Table** | Full-featured data grid with column controls |
| **Card** | Content container with header, body, and footer |
| **Badge** | Status labels and counters |
| **Avatar** | User avatars with fallback initials |
| **Kbd** | Keyboard shortcut display |
| **Typography** | Heading and prose components |
| **Skeleton** | Loading placeholder |
| **Empty** | Empty state illustration |
| **Chart** | Data visualization (Recharts v3) |

### Overlays

| Component | Description |
| --- | --- |
| **Dialog** | Modal dialog with focus trapping |
| **Alert Dialog** | Confirmation dialog with required action |
| **Sheet** | Slide-in panel from any edge |
| **Drawer** | Bottom sheet with drag-to-dismiss |
| **Dropdown Menu** | Context-aware dropdown with keyboard navigation |
| **Context Menu** | Right-click context menu |
| **Popover** | Positioned floating panel |
| **Tooltip** | Hover/focus information overlay |
| **Hover Card** | Rich content on hover |

### Layout

| Component | Description |
| --- | --- |
| **Accordion** | Collapsible content sections |
| **Collapsible** | Single collapsible region |
| **Aspect Ratio** | Fixed aspect ratio container |
| **Resizable** | Resizable panels with drag handles |
| **Scroll Area** | Custom scrollbar with cross-browser styling |
| **Separator** | Visual divider |
| **Carousel** | Swipeable content carousel |
| **Preview Panel** | Content preview with multiple layout modes |

### Feedback

| Component | Description |
| --- | --- |
| **Alert** | Status messages with icon and description |
| **Sonner** | Toast notifications |
| **Progress** | Progress bar with animation |
| **Toggle** | Pressed/unpressed state button |
| **Toggle Group** | Multi-toggle selection |

***

## The CLI Workflow

Adding components is a single command:

```bash
# Initialize a new project with components
bunx @gentleduck/cli init button dialog input select

# Add more components later
bunx @gentleduck/cli add command combobox data-table
```

The CLI:

1. Resolves dependencies between components (e.g. `combobox` needs `popover` + `command`).
2. Copies source files into the project.
3. Installs npm dependencies (`@gentleduck/primitives`, `@gentleduck/variants`, etc.).
4. Configures Tailwind CSS when needed.

### Why Copy Source?

Most component libraries are black boxes. You install a package, use the API, and
hope the defaults match your design. When they don't, you fight the abstraction with
CSS overrides, wrapper components, or abandoned forks.

Duck UI takes a different approach:

* **Full control** — every component is a file you own. Change the border radius,
  swap an icon, add a prop, remove a feature.
* **No version lock** — your code, your pace. No coupling to upstream releases.
* **Learn by reading** — the source is right there. See exactly how a dialog
  manages focus or how a combobox handles keyboard events.
* **Tree-shaking by default** — only the components you use ship. No dead code in
  the bundle.

Run `@gentleduck/cli add button` and you get the full `button.tsx` source in your
project. It's not a dependency — it's your code.

***

## Built on the Ecosystem

Every component uses the same GentleDuck packages you can adopt on their own:

* **@gentleduck/primitives** — headless behavior (focus, keyboard, ARIA).
* **@gentleduck/variants** — type-safe styling with `cva()`.
* **@gentleduck/hooks** — React hooks for component logic.
* **@gentleduck/motion** — enter/exit animations.
* **@gentleduck/libs** — utilities (`cn`, `Slot`, `Portal`).

The components are the reference implementation of these packages working together.
Read the source to learn the patterns and apply them to custom components.

***

## Getting Started