``` ## Dark Mode Dark mode is toggled by adding the `.dark` class to the `` element (same convention as shadcn/ui). The same variable names are redefined with dark values: ```css .dark { --background: oklch(0.145 0 0); --foreground: oklch(0.985 0 0); --primary: oklch(60.48% 0.2165 257.21); /* ... */ } ``` Components automatically adapt -- no extra props needed. ## Typography | Token | Value | |---|---| | `--font-sans` | `"Manrope", sans-serif` | | `--font-mono` | `"Fira Code", monospace` | Use in Tailwind: `font-sans`, `font-mono`. ## Easing Curves | Token | Value | Use case | |---|---|---| | `--ease-fluid` | `cubic-bezier(0.3, 0, 0, 1)` | General transitions | | `--ease-snappy` | `cubic-bezier(0.2, 0, 0, 1)` | Quick, responsive motion | Use in Tailwind: `ease-fluid`, `ease-snappy`. ## Component Sizing | Token | Value | |---|---| | `--spacing-ui-height` | `35px` | | `--spacing-ui-icon-height` | `calc(var(--spacing-ui-height) * 0.5)` | ## Z-Index Layers The z-index system provides ordered layers to prevent stacking conflicts: | Token | Value | Use case | |---|---|---| | `--z-base` | `0` | Default content | | `--z-dropdowns` | `200` | Select popups, menus | | `--z-tooltips` | `400` | Tooltip overlays | | `--z-overlays` | `500` | General overlays | | `--z-drawers` | `600` | Side/bottom drawers | | `--z-modals` | `700` | Modal dialogs | | `--z-notifications` | `800` | Toast notifications | ## Border Radius | Token | Value | |---|---| | `--radius-sm` | `calc(var(--radius) - 4px)` | | `--radius-md` | `calc(var(--radius) - 2px)` | | `--radius-lg` | `var(--radius)` (0.625rem) | | `--radius-xl` | `calc(var(--radius) + 4px)` | ## Chart Colors Five chart colors are provided for data visualization, compatible with shadcn/ui charting: ```css --chart-1: oklch(0.646 0.222 41.116); --chart-2: oklch(0.6 0.118 184.704); --chart-3: oklch(0.398 0.07 227.392); --chart-4: oklch(0.828 0.189 84.429); --chart-5: oklch(0.769 0.188 70.08); ``` ## Customization To override tokens, redefine the CSS variables after importing the theme: ```css @import "chunks-ui/theme.css"; :root { --primary: oklch(70% 0.2 150); --radius: 0.5rem; } ``` All components will pick up the new values automatically. --- # Components --- # Accordion A vertically stacked set of collapsible sections built on Base UI's `Accordion` primitive. Each item has a trigger header that reveals its panel with an animated height transition. ## Import ```tsx import { Accordion } from "chunks-ui"; ``` ## Basic Usage ```tsx What is chunks-ui?

A personal React component library.

Is it accessible?

Yes — keyboard nav and ARIA handled by Base UI.

``` ## Multiple Open Items By default only one item can be open at a time. Set `multiple` to allow expanding several items simultaneously: ```tsx {/* items */} ``` ## Default Open Pass an array of item values to `defaultValue` to start with those items expanded: ```tsx {/* items */} ``` ## Controlled ```tsx function ControlledAccordion() { const [value, setValue] = useState([]); return ( Section

Content

); } ``` ## Disabled Item Set `disabled` on `Accordion.Item` to prevent it from being opened: ```tsx Unavailable

Unreachable content.

``` ## Animation The panel height animates using CSS transitions via Base UI's `--accordion-panel-height` CSS variable. No JavaScript animation library is required. To opt out, override the `transition` class on `Accordion.Panel`. Respects `prefers-reduced-motion` — the transition duration collapses to `0` when the user has reduced motion enabled. ## Compound Parts | Part | Description | |---|---| | `Accordion.Root` | State container. Manages which items are open. | | `Accordion.Item` | Wraps a single collapsible section. Requires a unique `value`. | | `Accordion.Header` | Semantic `

` wrapper around the trigger. | | `Accordion.Trigger` | Clickable button that toggles the panel. Includes the chevron icon. | | `Accordion.Panel` | The collapsible content area. Animates height on open/close. | ## Accordion.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `string[]` | -- | Controlled open items | | `defaultValue` | `string[]` | `[]` | Initially open items (uncontrolled) | | `onValueChange` | `(value: string[]) => void` | -- | Called when open items change | | `multiple` | `boolean` | `false` | Allow multiple items open simultaneously | | `className` | `string` | -- | Additional CSS classes | ## Accordion.Item Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `string` | required | Unique identifier for this item | | `disabled` | `boolean` | `false` | Prevent this item from being opened | | `className` | `string` | -- | Additional CSS classes | ## Accordion.Trigger Props | Prop | Type | Default | Description | |---|---|---|---| | `children` | `ReactNode` | required | Trigger label content | | `className` | `string` | -- | Additional CSS classes | ## Accordion.Panel Props | Prop | Type | Default | Description | |---|---|---|---| | `children` | `ReactNode` | -- | Panel content | | `className` | `string` | -- | Additional CSS classes | --- # Avatar Displays a user avatar image with automatic fallback to initials. Supports numeric sizing and multiple shapes. ## Import ```tsx import { Avatar } from 'chunks-ui' ``` ## Basic Usage With an image: ```tsx ``` Without an image (shows initials derived from `alt`): ```tsx ``` This renders "JD" as fallback initials. ## Custom Fallback Override the auto-generated initials with the `fallback` prop: ```tsx ``` ## Sizes The `size` prop accepts a numeric value in pixels:
{[10, 20, 30, 40, 50, 60, 100].map(size => (

{size}px

))} ## Shapes ```tsx ``` ## Initials Generation When no `src` is provided and no `fallback` is set, initials are automatically generated from the `alt` text: - `"Jane Doe"` produces `"JD"` - `"Alice B. Charlie"` produces `"AB"` (first two initials) - Single word `"Admin"` produces `"A"` ## Props | Prop | Type | Default | Description | | ----------- | ----------------------------------- | ---------- | -------------------------------------------------------------- | | `src` | `string` | -- | Image URL. Shows image when provided, initials otherwise. | | `alt` | `string` | -- | Alt text for the image. Used to generate initials as fallback. | | `fallback` | `string` | -- | Explicit fallback text (overrides auto-generated initials). | | `size` | `number` | `40` | Avatar dimensions in pixels. | | `shape` | `"circle" \| "rounded" \| "square"` | `"circle"` | Avatar shape. | | `className` | `string` | -- | Additional CSS classes. | All other props are forwarded to the root `` element. --- # Button A styled button component built on Base UI's `Button` primitive. Supports multiple visual variants, semantic colors, loading state, and start/end icons. ## Import ```tsx import { Button } from 'chunks-ui' ``` ## Basic Usage ```tsx ``` ## Variants The `variant` prop controls the visual style: ```tsx ``` ## Colors The `color` prop sets the semantic color: ```tsx ``` Colors work with all variants: ```tsx ``` ## Loading State When `loading` is `true`, the button shows a `Loader` spinner in place of the `startIcon` and becomes disabled: ```tsx ``` The button remains focusable while loading (for accessibility) but click events are suppressed. ## Icons ```tsx ``` Icons are hidden during loading state. The `startIcon` slot is replaced by the `Loader`. ## Props | Prop | Type | Default | Description | | ----------- | --------------------------------------------------------------------- | ------------- | ------------------------------------ | | `variant` | `"contained" \| "outlined" \| "text"` | `"contained"` | Visual style | | `color` | `"primary" \| "destructive" \| "success" \| "warning" \| "secondary"` | `"primary"` | Semantic color | | `loading` | `boolean` | `false` | Show spinner and disable interaction | | `startIcon` | `ReactNode` | -- | Icon before children | | `endIcon` | `ReactNode` | -- | Icon after children | | `disabled` | `boolean` | `false` | Disable the button | | `className` | `string` | -- | Additional CSS classes | All other props are forwarded to the underlying Base UI `Button`. --- # Calendar A standalone date picker grid built without an external primitive. Supports controlled and uncontrolled selection, min/max bounds, and custom disabled-date predicates. ## Import ```tsx import { Calendar } from "chunks-ui"; ``` ## Basic Usage ```tsx ``` ## Controlled ```tsx function ControlledCalendar() { const [date, setDate] = useState(null); return ( ); } ``` ## Disabled Dates Use `min`/`max` to set a date range, or `isDateDisabled` to disable individual dates with a predicate: ```tsx const today = new Date(); const isWeekend = (date: Date) => date.getDay() === 0 || date.getDay() === 6; ``` ## Calendar Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `Date \| null` | -- | Controlled selected date | | `defaultValue` | `Date \| null` | `null` | Initial selected date (uncontrolled) | | `onValueChange` | `(date: Date \| null) => void` | -- | Called when the selected date changes | | `min` | `Date` | -- | Earliest selectable date (inclusive) | | `max` | `Date` | -- | Latest selectable date (inclusive) | | `isDateDisabled` | `(date: Date) => boolean` | -- | Predicate to disable individual dates | | `className` | `string` | -- | Additional CSS classes | --- # Card A compound layout component for displaying grouped content. Built with plain HTML elements (no Base UI dependency). Follows the compound pattern: `Card.Root`, `Card.Header`, `Card.Title`, `Card.Description`, `Card.Content`, `Card.Footer`. ## Import ```tsx import { Card } from "chunks-ui"; ``` ## Basic Usage ```tsx Project Alpha A brief description of the project.
Main content goes here.
``` ## Minimal Card You can use any subset of compound parts: ```tsx
Simple card with content only.
``` ## With Custom Content ```tsx Team Members Manage your team members and roles.

Alice Johnson

Admin

Bob Smith

Member

``` ## Compound Parts | Part | Description | |---|---| | `Card.Root` | Outer container. Rounded border, background, and shadow. | | `Card.Header` | Top section with vertical flex layout and padding (`p-6`). | | `Card.Title` | Heading rendered as `
`. Semibold, tight tracking. | | `Card.Description` | Subtext below the title. `text-muted-foreground`. | | `Card.Content` | Main body area. Padding `p-6 pt-0`. | | `Card.Footer` | Bottom section. Horizontal flex with `gap-2 p-6 pt-0`. | ## Props All compound parts accept standard HTML `div` props (or `h3`/`p` for Title/Description) plus `className` for additional styling. There are no component-specific variant props. --- # Checkbox A styled checkbox built on Base UI's `Checkbox` primitive. Supports checked, unchecked, and indeterminate states with a compound component pattern. ## Import ```tsx import { Checkbox } from "chunks-ui"; ``` ## Basic Usage ```tsx ``` ## With Label Use the `Field` component to associate a label: ```tsx
Accept terms and conditions
``` ## Controlled ```tsx function ControlledCheckbox() { const [checked, setChecked] = useState(false); return ( ); } ``` ## Indeterminate State The indeterminate state is used for "select all" patterns where some items are checked: ```tsx ``` ## Disabled ```tsx ``` ## Compound Parts | Part | Description | |---|---| | `Checkbox.Root` | The checkbox control. Handles checked state and keyboard interaction. | | `Checkbox.Indicator` | Renders the check/indeterminate icon inside the root. | ## Checkbox.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `checked` | `boolean \| "indeterminate"` | -- | Controlled checked state | | `defaultChecked` | `boolean` | `false` | Initial checked state (uncontrolled) | | `onCheckedChange` | `(checked: boolean) => void` | -- | Called when checked state changes | | `disabled` | `boolean` | `false` | Disable the checkbox | | `className` | `string` | -- | Additional CSS classes | ## Checkbox.Indicator Props | Prop | Type | Default | Description | |---|---|---|---| | `className` | `string` | -- | Additional CSS classes | --- # Chip A small label/tag component with optional remove functionality. Uses the `ClearButton` component internally for the dismiss action. ## Import ```tsx import { Chip } from "chunks-ui"; ``` ## Basic Usage ```tsx Default ``` ## Colors ```tsx Primary Destructive Success Warning Secondary ``` Each color applies a light tinted background with matching text and border (e.g. `bg-primary/10 text-primary border-primary/30`). ## Removable Chip Pass an `onRemove` callback to show a close button: ```tsx function TagList() { const [tags, setTags] = useState(["React", "TypeScript", "Tailwind"]); return (
{tags.map((tag) => ( setTags((prev) => prev.filter((t) => t !== tag))} > {tag} ))}
); } ``` ## Props | Prop | Type | Default | Description | |---|---|---|---| | `color` | `"primary" \| "destructive" \| "success" \| "warning" \| "secondary"` | `"secondary"` | Semantic color variant | | `onRemove` | `() => void` | -- | Show remove button; called on click | | `className` | `string` | -- | Additional CSS classes | | `children` | `ReactNode` | -- | Chip label content | All other props are forwarded to the root `` element. --- # ClearButton A small circular icon button for clearing or dismissing values. Used internally by `Input` (via `onClear`) and `Chip` (via `onRemove`), but also exported for direct use. ## Import ```tsx import { ClearButton } from 'chunks-ui' ``` ## Basic Usage ```tsx console.log('Cleared')} /> ``` ## Custom Label Pass `aria-label` directly to override the default: ```tsx ``` Default label is `"Clear"`. ## Props | Prop | Type | Default | Description | | ----------- | ------------ | ------- | ---------------------- | | `className` | `string` | -- | Additional CSS classes | | `onClick` | `() => void` | -- | Click handler | | `disabled` | `boolean` | `false` | Disable the button | All HTML `
``` ## With Backdrop The `Dialog.Backdrop` renders a semi-transparent black overlay (`bg-black/50`) with a fade transition. It uses the `z-overlays` z-index layer: ```tsx Show Dialog with backdrop The backdrop dims the content behind the dialog. Close ``` ## Controlled ```tsx function ControlledDialog() { const [open, setOpen] = useState(false); return ( Open Controlled Dialog You can control the open state. Done ); } ``` ## Animation The popup enters with a scale-up + fade transition (`scale-95` to `scale-100`, `opacity-0` to `opacity-1`) over 200ms. The backdrop fades in/out independently. ## Compound Parts | Part | Description | |---|---| | `Dialog.Root` | State container. Manages open/close. | | `Dialog.Trigger` | Button that opens the dialog. | | `Dialog.Portal` | Renders children in a portal outside the DOM tree. | | `Dialog.Backdrop` | Semi-transparent overlay behind the dialog. `z-overlays` (500). | | `Dialog.Popup` | Centered content panel. `z-modals` (700). Max width `max-w-md`. | | `Dialog.Title` | Dialog heading. Rendered as a semibold `text-lg`. | | `Dialog.Description` | Supporting text below the title. Rendered in `text-muted-foreground`. | | `Dialog.Close` | Button that closes the dialog. | ## Dialog.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `open` | `boolean` | -- | Controlled open state | | `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) | | `onOpenChange` | `(open: boolean) => void` | -- | Called when open state changes | | `modal` | `boolean` | `true` | Whether the dialog is modal | --- # Drawer A side or bottom sheet overlay built on Base UI's `Dialog` primitive. Slides in from the left, right, or bottom edge with a snappy easing transition. ## Import ```tsx import { Drawer } from "chunks-ui"; ``` ## Basic Usage ```tsx Open Drawer Navigation Browse the app sections.
Home Settings
Close ``` ## Side Variants The `side` prop on `Drawer.Popup` controls which edge the drawer slides from: ```tsx {/* Right side (default) /} ... {/ Left side /} ... {/ Bottom sheet /} ... ``` - `left` and `right` drawers have a fixed width of `w-80`. - `bottom` drawer spans the full width with automatic height and rounded top corners. ## Controlled ```tsx function ControlledDrawer() { const [open, setOpen] = useState(false); return ( Menu Menu Close ); } ``` ## Animation The drawer slides in from its designated edge using `translate-x` (left/right) or `translate-y` (bottom) with the `ease-snappy` easing curve over 200ms. The backdrop fades in independently. ## Compound Parts | Part | Description | |---|---| | `Drawer.Root` | State container. Manages open/close state. | | `Drawer.Trigger` | Button that opens the drawer. | | `Drawer.Portal` | Renders children in a portal. | | `Drawer.Backdrop` | Semi-transparent overlay. `z-drawers` (600). | | `Drawer.Popup` | The sliding panel. `z-drawers` (600). Accepts `side` prop. | | `Drawer.Title` | Drawer heading. | | `Drawer.Description` | Supporting description text. | | `Drawer.Close` | Button that closes the drawer. | ## Drawer.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `open` | `boolean` | -- | Controlled open state | | `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) | | `onOpenChange` | `(open: boolean) => void` | -- | Called when open state changes | ## Drawer.Popup Props | Prop | Type | Default | Description | |---|---|---|---| | `side` | `"left" \| "right" \| "bottom"` | `"right"` | Which edge the drawer slides from | | `className` | `string` | -- | Additional CSS classes | --- # Field A form field wrapper built on Base UI's `Field` primitive. Provides label, description, error message, and validation state management for form controls like `Input`, `Textarea`, `Checkbox`, etc. ## Import ```tsx import { Field } from "chunks-ui"; ``` ## Basic Usage ```tsx Email ``` ## With Description ```tsx Password Must be at least 8 characters. ``` ## Validation Error Set `invalid` on `Field.Root` to activate error styling. The `Field.Error` message appears and the input receives `data-[invalid]` for red border styling: ```tsx Email Please enter a valid email address. ``` ## With Textarea ```tsx Message Describe your issue in detail. </Field.Root> ``` ## Native Validation Use `Field.Validity` for native constraint validation: ```tsx <Field.Root> <Field.Label>Username</Field.Label> <Field.Control render={<Input />} required minLength={3} /> <Field.Validity> {(state) => state.validity.valueMissing ? ( <Field.Error>Username is required.</Field.Error> ) : state.validity.tooShort ? ( <Field.Error>Must be at least 3 characters.</Field.Error> ) : null } </Field.Validity> </Field.Root> ``` ## Disabled State Labels dim to 50% opacity when the field is disabled: ```tsx <Field.Root disabled> <Field.Label>Locked Field</Field.Label> <Input disabled value="Cannot edit" /> </Field.Root> ``` ## Compound Parts | Part | Description | |---|---| | `Field.Root` | Wrapper element. Vertical flex with `gap-1`. Manages `invalid` and `disabled` state. | | `Field.Label` | Form label. `text-sm font-medium`. Dims when disabled. | | `Field.Description` | Help text below the label. `text-xs text-muted-foreground`. | | `Field.Error` | Error message. `text-xs text-destructive`. Only visible when `invalid`. | | `Field.Control` | Connects a form control to the field (for native validation). Uses `render` prop. | | `Field.Validity` | Render prop for accessing native validity state. | ## Field.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `invalid` | `boolean` | `false` | Marks the field as invalid, showing error styles | | `disabled` | `boolean` | `false` | Disables the field and dims the label | | `className` | `string` | -- | Additional CSS classes | --- # Input A styled text input built on Base UI's `Input` primitive. Supports start/end adornments, a clear button, and error states via `data-[invalid]`. ## Import ```tsx import { Input } from 'chunks-ui' ``` ## Basic Usage ```tsx <Input placeholder="Enter your name" /> ``` ## Adornments Use `startAdornment` and `endAdornment` to place icons or text at the edges of the input: ```tsx <Input startAdornment={<SearchIcon className="size-4" />} placeholder="Search..." /> ``` ```tsx <Input endAdornment={<span className="text-xs text-muted-foreground">USD</span>} placeholder="0.00" /> ``` ## Clear Button Pass an `onClear` callback to show a built-in clear button (uses the `ClearButton` component internally): ```tsx export const InputWithClearButton = () => { const [value, setValue] = useState('') return ( <Input value={value} onChange={e => setValue(e.target.value)} onClear={() => setValue('')} placeholder="Search..." /> ) } ``` ## Error State The input styles change when the `data-invalid` attribute is present (set automatically by `Field.Root` with `invalid` prop, or manually): ```tsx <Field.Root invalid> <Field.Label>Email</Field.Label> <Input placeholder="user@example.com" /> <Field.Error>Invalid email address</Field.Error> </Field.Root> ``` ## With Field Wrap `Input` in a `Field` for labels, descriptions, and validation: ```tsx <Field.Root> <Field.Label>Username</Field.Label> <Field.Description>Choose a unique username</Field.Description> <Input placeholder="johndoe" /> </Field.Root> ``` ## Props | Prop | Type | Default | Description | | ---------------- | ------------ | ------- | ---------------------------------- | | `startAdornment` | `ReactNode` | -- | Element before the input text | | `endAdornment` | `ReactNode` | -- | Element after the input text | | `onClear` | `() => void` | -- | Show clear button; called on click | | `className` | `string` | -- | Additional CSS classes | All other props are forwarded to the underlying Base UI `Input` (supports `value`, `onChange`, `placeholder`, `disabled`, etc.). --- # Loader An animated SVG spinner for loading states. Used internally by `Button` during its loading state, and available for standalone use. ## Import ```tsx import { Loader } from "chunks-ui"; ``` ## Basic Usage The spinner inherits the current text color of its parent, so it always keeps contrast with the background. ```tsx <Loader /> ``` ## Custom Color Override the color via `className`: ```tsx <Loader className="text-primary" /> <Loader className="text-muted-foreground" /> ``` ## Inline with Text ```tsx <div className="flex items-center gap-2 text-muted-foreground"> <Loader /> <span>Loading data...</span> </div> ``` ## Full-Page Loading ```tsx <div className="flex h-screen items-center justify-center"> <Loader /> </div> ``` ## Props | Prop | Type | Default | Description | |---|---|---|---| | `className` | `string` | -- | Additional CSS classes. Use `text-` utilities to override the color. | All other props are forwarded to the root `<svg>` element. The spinner uses `animate-spin` for rotation and is marked `aria-hidden="true"`. --- # Menu A dropdown menu built on Base UI's `Menu` primitive. Supports plain items, groups, checkbox items, and radio groups. Animates with Motion when available, falls back to CSS transitions. ## Import ```tsx import { Menu } from "chunks-ui"; ``` ## Basic Usage ```tsx <Menu.Root> <Menu.Trigger>Options</Menu.Trigger> <Menu.Content> <Menu.Item>View profile</Menu.Item> <Menu.Item>Edit settings</Menu.Item> <Menu.Separator /> <Menu.Item>Sign out</Menu.Item> </Menu.Content> </Menu.Root> ``` ## Groups Use `Menu.Group` with `Menu.GroupLabel` to organize items into labelled sections: ```tsx <Menu.Root> <Menu.Trigger>Actions</Menu.Trigger> <Menu.Content> <Menu.Group> <Menu.GroupLabel>File</Menu.GroupLabel> <Menu.Item>New file</Menu.Item> <Menu.Item>Open...</Menu.Item> </Menu.Group> <Menu.Separator /> <Menu.Group> <Menu.GroupLabel>Edit</Menu.GroupLabel> <Menu.Item>Undo</Menu.Item> <Menu.Item>Redo</Menu.Item> </Menu.Group> </Menu.Content> </Menu.Root> ``` ## Checkbox Items `Menu.CheckboxItem` keeps a checked state. Pair with `Menu.CheckboxItemIndicator` to show a check mark: ```tsx <Menu.CheckboxItem checked={showGrid} onCheckedChange={setShowGrid}> <Menu.CheckboxItemIndicator>✓</Menu.CheckboxItemIndicator> Show grid </Menu.CheckboxItem> ``` ## Radio Group `Menu.RadioGroup` enforces single selection among `Menu.RadioItem` children: ```tsx <Menu.RadioGroup value={theme} onValueChange={setTheme}> <Menu.RadioItem value="light"> <Menu.RadioItemIndicator>•</Menu.RadioItemIndicator> Light </Menu.RadioItem> <Menu.RadioItem value="dark"> <Menu.RadioItemIndicator>•</Menu.RadioItemIndicator> Dark </Menu.RadioItem> </Menu.RadioGroup> ``` ## Positioning `Menu.Content` accepts positioning props forwarded to Base UI's positioner: ```tsx <Menu.Content side="right" align="start" sideOffset={8}> ... </Menu.Content> ``` ## Compound Parts | Part | Description | |---|---| | `Menu.Root` | State container. Manages open/close. | | `Menu.Trigger` | Element that opens the menu. | | `Menu.Content` | Portal + positioner + popup panel. Default `sideOffset={4}`. | | `Menu.Item` | A single actionable menu entry. | | `Menu.Separator` | Horizontal divider between groups of items. | | `Menu.Group` | Semantic grouping wrapper for related items. | | `Menu.GroupLabel` | Non-interactive label for a `Menu.Group`. | | `Menu.CheckboxItem` | Menu item with a toggleable checked state. | | `Menu.CheckboxItemIndicator` | Visual indicator shown when `CheckboxItem` is checked. | | `Menu.RadioGroup` | Enforces single selection among `RadioItem` children. | | `Menu.RadioItem` | Selectable item within a `Menu.RadioGroup`. | | `Menu.RadioItemIndicator` | Visual indicator shown when `RadioItem` is selected. | | `Menu.Arrow` | SVG arrow pointing to the trigger. | ## Menu.Content Props | Prop | Type | Default | Description | |---|---|---|---| | `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Preferred side relative to the trigger | | `sideOffset` | `number` | `4` | Distance from the trigger | | `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along the side | | `alignOffset` | `number` | `0` | Offset from the alignment edge | | `className` | `string` | -- | Additional CSS classes | ## Menu.Item Props | Prop | Type | Default | Description | |---|---|---|---| | `disabled` | `boolean` | `false` | Prevent interaction and dim the item | | `onClick` | `() => void` | -- | Called when the item is activated | | `className` | `string` | -- | Additional CSS classes | --- # NumberField A numeric input built on Base UI's `NumberField` primitive. Supports increment/decrement buttons, min/max/step constraints, and scrub-area drag interaction. ## Import ```tsx import { NumberField } from "chunks-ui"; ``` ## Basic Usage ```tsx <NumberField.Root defaultValue={10}> <NumberField.Group> <NumberField.Decrement /> <NumberField.Input /> <NumberField.Increment /> </NumberField.Group> </NumberField.Root> ``` ## Min, Max, and Step Use `min`, `max`, and `step` to constrain the value: ```tsx <NumberField.Root defaultValue={5} min={1} max={20}> <NumberField.Group> <NumberField.Decrement /> <NumberField.Input /> <NumberField.Increment /> </NumberField.Group> </NumberField.Root> ``` ## Scrub Area Wrap a label with `NumberField.ScrubArea` to allow click-and-drag adjustment. The cursor hides during the scrub gesture via `NumberField.ScrubAreaCursor`: ```tsx <NumberField.Root defaultValue={100}> <NumberField.ScrubArea> <span>Drag to adjust</span> <NumberField.ScrubAreaCursor /> </NumberField.ScrubArea> <NumberField.Group> <NumberField.Decrement /> <NumberField.Input /> <NumberField.Increment /> </NumberField.Group> </NumberField.Root> ``` ## Disabled ```tsx <NumberField.Root defaultValue={42} disabled> <NumberField.Group> <NumberField.Decrement /> <NumberField.Input /> <NumberField.Increment /> </NumberField.Group> </NumberField.Root> ``` ## Compound Parts | Part | Description | |---|---| | `NumberField.Root` | State container. Manages value, min, max, step, and disabled state. | | `NumberField.Group` | Wraps `Decrement`, `Input`, and `Increment` into a single bordered control. | | `NumberField.Input` | The text input. Displays and accepts the numeric value. | | `NumberField.Decrement` | Button that decrements the value by `step`. | | `NumberField.Increment` | Button that increments the value by `step`. | | `NumberField.ScrubArea` | A region the user can click-drag to change the value. | | `NumberField.ScrubAreaCursor` | A virtual cursor shown during the scrub gesture (hidden by default). | ## NumberField.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `number` | -- | Controlled value | | `defaultValue` | `number` | -- | Initial value (uncontrolled) | | `onValueChange` | `(value: number) => void` | -- | Called when value changes | | `min` | `number` | -- | Minimum allowed value | | `max` | `number` | -- | Maximum allowed value | | `step` | `number` | `1` | Step increment | | `disabled` | `boolean` | `false` | Disable all interaction | | `className` | `string` | -- | Additional CSS classes | --- # Popover A positioned popup built on Base UI's `Popover` primitive. Includes built-in Floating UI positioning, an optional arrow, and scale/fade enter/exit transitions. ## Import ```tsx import { Popover } from "chunks-ui"; ``` ## Basic Usage ```tsx <Popover.Root> <Popover.Trigger>More info</Popover.Trigger> <Popover.Content> <Popover.Title>Details</Popover.Title> <Popover.Description> This is additional context about the feature. </Popover.Description> </Popover.Content> </Popover.Root> ``` ## With Arrow ```tsx <Popover.Root> <Popover.Trigger>Help</Popover.Trigger> <Popover.Content> <Popover.Arrow /> <Popover.Title>Need help?</Popover.Title> <Popover.Description> Contact support at help@example.com. </Popover.Description> </Popover.Content> </Popover.Root> ``` ## With Close Button ```tsx <Popover.Root> <Popover.Trigger>Open</Popover.Trigger> <Popover.Content> <div className="flex items-center justify-between"> <Popover.Title>Settings</Popover.Title> <Popover.Close>Close</Popover.Close> </div> <Popover.Description> Configure your preferences here. </Popover.Description> </Popover.Content> </Popover.Root> ``` ## Positioning The `Popover.Content` uses Base UI's built-in Floating UI integration. It has a default `sideOffset` of `8px`. You can customize placement via `side` and `align` props: ```tsx <Popover.Content side="bottom" align="start"> ... </Popover.Content> ``` ## Compound Parts | Part | Description | |---|---| | `Popover.Root` | State container. Manages open/close. | | `Popover.Trigger` | Element that toggles the popover. | | `Popover.Content` | Portal + positioner + popup panel. Default `sideOffset={8}`. Accepts `side`, `align`, `alignOffset` props. | | `Popover.Arrow` | SVG arrow pointing to the trigger. Filled with `--popover` color. | | `Popover.Title` | Popover heading. Semibold `text-sm`. | | `Popover.Description` | Supporting text. `text-muted-foreground`. | | `Popover.Close` | Button that closes the popover. | ## Popover.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `open` | `boolean` | -- | Controlled open state | | `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) | | `onOpenChange` | `(open: boolean) => void` | -- | Called when open state changes | ## Popover.Content Props | Prop | Type | Default | Description | |---|---|---|---| | `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Preferred side | | `sideOffset` | `number` | `8` | Distance from the trigger | | `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along the side | | `alignOffset` | `number` | `0` | Offset from the alignment edge | | `className` | `string` | -- | Additional CSS classes | --- # Progress A progress bar built on Base UI's `Progress` primitive. Supports determinate values and an indeterminate loading state. ## Import ```tsx import { Progress } from "chunks-ui"; ``` ## Basic Usage Pass `value` and `max` to show a determinate progress bar: ```tsx <Progress.Root value={65} max={100}> <Progress.Track> <Progress.Indicator /> </Progress.Track> </Progress.Root> ``` ## Indeterminate Omit `value` (or pass `null`) to activate the indeterminate pulse animation: ```tsx <Progress.Root> <Progress.Track> <Progress.Indicator /> </Progress.Track> </Progress.Root> ``` ## Multiple Values ## Compound Parts | Part | Description | |---|---| | `Progress.Root` | State container. Holds `value`, `max`, and exposes `data-indeterminate` when no value is set. | | `Progress.Track` | The background rail. Full-width pill shape. | | `Progress.Indicator` | Fills the track proportionally. Pulses when indeterminate. | ## Progress.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `number \| null` | `null` | Current progress value. `null` triggers indeterminate state. | | `max` | `number` | `100` | Maximum value | | `aria-label` | `string` | -- | Accessible label for the progress bar | | `className` | `string` | -- | Additional CSS classes | --- # Radio Radio buttons built on Base UI's `Radio` and `RadioGroup` primitives. Includes a group wrapper for managing single-selection among multiple options. ## Import ```tsx import { Radio } from "chunks-ui"; ``` ## Basic Usage ```tsx <Radio.Group defaultValue="option-a"> <Radio.Item value="option-a">Option A</Radio.Item> <Radio.Item value="option-b">Option B</Radio.Item> <Radio.Item value="option-c">Option C</Radio.Item> </Radio.Group> ``` ## Controlled ```tsx function ControlledRadio() { const [value, setValue] = useState("a"); return ( <Radio.Group value={value} onValueChange={setValue}> <Radio.Item value="a">Option A</Radio.Item> <Radio.Item value="b">Option B</Radio.Item> </Radio.Group> ); } ``` ## Disabled Disable individual radio buttons or the entire group: ```tsx <Radio.Group disabled> <Radio.Item value="a">Disabled option</Radio.Item> </Radio.Group> ``` ## Compound Parts | Part | Description | |---|---| | `Radio.Group` | Wrapper that manages value state. Renders a vertical flex column by default. | | `Radio.Item` | Convenience compound: label + radio + indicator in one element. | | `Radio.Root` | Individual radio button. Renders a circular control. | | `Radio.Indicator` | The inner dot that appears when the radio is selected. | ## Radio.Group Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `string` | -- | Controlled selected value | | `defaultValue` | `string` | -- | Initial value (uncontrolled) | | `onValueChange` | `(value: string) => void` | -- | Called when selection changes | | `disabled` | `boolean` | `false` | Disable all radio buttons in the group | | `className` | `string` | -- | Additional CSS classes | ## Radio.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `string` | required | The value this radio represents | | `disabled` | `boolean` | `false` | Disable this radio button | | `className` | `string` | -- | Additional CSS classes | --- # ScrollArea A custom scrollable container built on Base UI's `ScrollArea` primitive. Hides native scrollbars and replaces them with styled overlays that appear on hover or scroll. ## Import ```tsx import { ScrollArea } from "chunks-ui"; ``` ## Basic Usage Vertical scrolling — constrain height on the root and the scrollbar renders automatically: ```tsx <ScrollArea.Root className="h-64 w-full rounded border border-border"> <ScrollArea.Viewport> <ScrollArea.Content> {/* tall content /} </ScrollArea.Content> </ScrollArea.Viewport> <ScrollArea.Scrollbar orientation="vertical"> <ScrollArea.Thumb /> </ScrollArea.Scrollbar> </ScrollArea.Root> ``` ## Horizontal Scrollbar Set `orientation="horizontal"` on the scrollbar for wide content: ```tsx <ScrollArea.Root className="w-full rounded border border-border"> <ScrollArea.Viewport> <ScrollArea.Content>{/ wide content /}</ScrollArea.Content> </ScrollArea.Viewport> <ScrollArea.Scrollbar orientation="horizontal"> <ScrollArea.Thumb /> </ScrollArea.Scrollbar> </ScrollArea.Root> ``` ## Both Axes Add both scrollbars and `ScrollArea.Corner` to fill the intersection: ```tsx <ScrollArea.Root className="h-48 w-full rounded border border-border"> <ScrollArea.Viewport> <ScrollArea.Content>{/ tall + wide content */}</ScrollArea.Content> </ScrollArea.Viewport> <ScrollArea.Scrollbar orientation="vertical"> <ScrollArea.Thumb /> </ScrollArea.Scrollbar> <ScrollArea.Scrollbar orientation="horizontal"> <ScrollArea.Thumb /> </ScrollArea.Scrollbar> <ScrollArea.Corner /> </ScrollArea.Root> ``` ## Compound Parts | Part | Description | |---|---| | `ScrollArea.Root` | Outer container. Sets `overflow: hidden` and positions scrollbars. | | `ScrollArea.Viewport` | The scrollable window. Native scrollbars are hidden via CSS. | | `ScrollArea.Content` | Wraps the actual content inside the viewport. | | `ScrollArea.Scrollbar` | The custom scrollbar track. Fades in on hover/scroll via `data-[hovering]` and `data-[scrolling]`. | | `ScrollArea.Thumb` | The draggable scrollbar handle. Expands the hit area with a negative margin. | | `ScrollArea.Corner` | Fills the corner square when both scrollbars are visible. | ## ScrollArea.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `className` | `string` | -- | Additional CSS classes. Set `height` here to enable vertical scrolling. | ## ScrollArea.Scrollbar Props | Prop | Type | Default | Description | |---|---|---|---| | `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Which axis the scrollbar controls | | `className` | `string` | -- | Additional CSS classes | --- # Select A styled single-select dropdown built on Base UI's `Select` primitive. Includes trigger, popup, items, grouped options, and built-in Floating UI positioning. ## Import ```tsx import { Select } from "chunks-ui"; ``` ## Basic Usage ```tsx <Select.Root> <Select.Trigger> <Select.Value placeholder="Choose a fruit" /> <Select.Icon /> </Select.Trigger> <Select.Portal> <Select.Positioner> <Select.Popup> <Select.Item value="apple"> <Select.ItemText>Apple</Select.ItemText> <Select.ItemIndicator /> </Select.Item> <Select.Item value="banana"> <Select.ItemText>Banana</Select.ItemText> <Select.ItemIndicator /> </Select.Item> <Select.Item value="cherry"> <Select.ItemText>Cherry</Select.ItemText> <Select.ItemIndicator /> </Select.Item> </Select.Popup> </Select.Positioner> </Select.Portal> </Select.Root> ``` ## Grouped Options ```tsx <Select.Root> <Select.Trigger> <Select.Value placeholder="Pick a color" /> <Select.Icon /> </Select.Trigger> <Select.Portal> <Select.Positioner> <Select.Popup> <Select.Group> <Select.GroupLabel>Warm</Select.GroupLabel> <Select.Item value="red"> <Select.ItemText>Red</Select.ItemText> <Select.ItemIndicator /> </Select.Item> <Select.Item value="orange"> <Select.ItemText>Orange</Select.ItemText> <Select.ItemIndicator /> </Select.Item> </Select.Group> <Select.Group> <Select.GroupLabel>Cool</Select.GroupLabel> <Select.Item value="blue"> <Select.ItemText>Blue</Select.ItemText> <Select.ItemIndicator /> </Select.Item> <Select.Item value="green"> <Select.ItemText>Green</Select.ItemText> <Select.ItemIndicator /> </Select.Item> </Select.Group> </Select.Popup> </Select.Positioner> </Select.Portal> </Select.Root> ``` ## Controlled ```tsx function ControlledSelect() { const [value, setValue] = useState(""); return ( <Select.Root value={value} onValueChange={setValue}> <Select.Trigger> <Select.Value placeholder="Select status" /> <Select.Icon /> </Select.Trigger> <Select.Portal> <Select.Positioner> <Select.Popup> <Select.Item value="active"> <Select.ItemText>Active</Select.ItemText> <Select.ItemIndicator /> </Select.Item> <Select.Item value="inactive"> <Select.ItemText>Inactive</Select.ItemText> <Select.ItemIndicator /> </Select.Item> </Select.Popup> </Select.Positioner> </Select.Portal> </Select.Root> ); } ``` ## Compound Parts | Part | Description | |---|---| | `Select.Root` | State container. Manages open/close and selected value. | | `Select.Trigger` | The button that opens the dropdown. Styled like an input. | | `Select.Value` | Displays the selected value or placeholder text. | | `Select.Icon` | Chevron icon inside the trigger. | | `Select.Portal` | Renders the popup in a portal. | | `Select.Positioner` | Handles Floating UI positioning. | | `Select.Popup` | The dropdown panel containing items. | | `Select.Item` | An individual selectable option. | | `Select.ItemText` | The text content of an item. | | `Select.ItemIndicator` | Checkmark shown for the selected item. | | `Select.Group` | Groups related items together. | | `Select.GroupLabel` | Label for a group of items. | ## Select.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `string` | -- | Controlled selected value | | `defaultValue` | `string` | -- | Initial value (uncontrolled) | | `onValueChange` | `(value: string) => void` | -- | Called when selection changes | | `open` | `boolean` | -- | Controlled open state | | `onOpenChange` | `(open: boolean) => void` | -- | Called when open state changes | ## Select.Trigger Props | Prop | Type | Default | Description | |---|---|---|---| | `disabled` | `boolean` | `false` | Disable the trigger | | `className` | `string` | -- | Additional CSS classes | --- # Separator A visual divider built on Base UI's `Separator` primitive. Supports horizontal and vertical orientations. ## Import ```tsx import { Separator } from "chunks-ui"; ``` ## Basic Usage Horizontal separator (default): ```tsx <div> <p>Content above</p> <Separator /> <p>Content below</p> </div> ``` ## Vertical ```tsx <div className="flex h-8 items-center gap-4"> <span>Left</span> <Separator orientation="vertical" /> <span>Right</span> </div> ``` ## In a List ```tsx <div className="flex flex-col"> <div className="py-2">Item 1</div> <Separator /> <div className="py-2">Item 2</div> <Separator /> <div className="py-2">Item 3</div> </div> ``` ## Props | Prop | Type | Default | Description | |---|---|---|---| | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Divider direction | | `className` | `string` | -- | Additional CSS classes | All other props are forwarded to the underlying Base UI `Separator`. ## Styling - Horizontal: `h-px w-full` with `bg-border` - Vertical: `w-px h-full` with `bg-border` --- # Slider A draggable range input built on Base UI's `Slider` primitive. Supports single values, ranges, horizontal and vertical orientations, and keyboard navigation. ## Import ```tsx import { Slider } from "chunks-ui"; ``` ## Basic Usage ```tsx <Slider.Root defaultValue={40}> <Slider.Control> <Slider.Track> <Slider.Indicator /> <Slider.Thumb aria-label="Value" /> </Slider.Track> </Slider.Control> </Slider.Root> ``` ## With Value Display Use `Slider.Value` to display the current value. Place it anywhere inside `Slider.Root`: ```tsx <Slider.Root defaultValue={60}> <div className="flex items-center justify-between"> <span className="text-sm text-muted-foreground">Volume</span> <Slider.Value /> </div> <Slider.Control> <Slider.Track> <Slider.Indicator /> <Slider.Thumb aria-label="Volume" /> </Slider.Track> </Slider.Control> </Slider.Root> ``` ## Range Slider Pass an array to `defaultValue` and render a `Slider.Thumb` with `index` for each handle: ```tsx <Slider.Root defaultValue={[20, 80]}> <Slider.Control> <Slider.Track> <Slider.Indicator /> <Slider.Thumb index={0} aria-label="Minimum" /> <Slider.Thumb index={1} aria-label="Maximum" /> </Slider.Track> </Slider.Control> </Slider.Root> ``` ## Vertical Orientation Set `orientation="vertical"` on the root. The track and indicator switch to a vertical layout automatically: ```tsx <Slider.Root defaultValue={50} orientation="vertical"> <Slider.Control> <Slider.Track> <Slider.Indicator /> <Slider.Thumb aria-label="Value" /> </Slider.Track> </Slider.Control> </Slider.Root> ``` ## Controlled ```tsx function ControlledSlider() { const [value, setValue] = useState(50); return ( <Slider.Root value={value} onValueChange={setValue}> <Slider.Control> <Slider.Track> <Slider.Indicator /> <Slider.Thumb aria-label="Value" /> </Slider.Track> </Slider.Control> </Slider.Root> ); } ``` ## Disabled ```tsx <Slider.Root defaultValue={50} disabled> <Slider.Control> <Slider.Track> <Slider.Indicator /> <Slider.Thumb aria-label="Value" /> </Slider.Track> </Slider.Control> </Slider.Root> ``` ## Compound Parts | Part | Description | |---|---| | `Slider.Root` | State container. Manages value, orientation, and disabled state. | | `Slider.Value` | Displays the current numeric value as text. | | `Slider.Control` | The interactive area. Handles pointer and keyboard events. | | `Slider.Track` | The background rail. Full width (or height when vertical). | | `Slider.Indicator` | Fills the track from origin to the current thumb position. | | `Slider.Thumb` | The draggable handle. Requires `aria-label` for accessibility. | ## Slider.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `number \| number[]` | -- | Controlled value | | `defaultValue` | `number \| number[]` | `0` | Initial value (uncontrolled) | | `onValueChange` | `(value: number \| number[]) => void` | -- | Called on value change | | `min` | `number` | `0` | Minimum value | | `max` | `number` | `100` | Maximum value | | `step` | `number` | `1` | Step increment | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction | | `disabled` | `boolean` | `false` | Disable interaction | | `className` | `string` | -- | Additional CSS classes | ## Slider.Thumb Props | Prop | Type | Default | Description | |---|---|---|---| | `index` | `number` | `0` | Which value this thumb controls (range sliders) | | `aria-label` | `string` | required | Accessible label for the thumb | | `className` | `string` | -- | Additional CSS classes | --- # Switch A toggle switch built on Base UI's `Switch` primitive. Provides an accessible on/off control with a sliding thumb animation. ## Import ```tsx import { Switch } from "chunks-ui"; ``` ## Basic Usage ```tsx <Switch.Root> <Switch.Thumb /> </Switch.Root> ``` ## With Label ```tsx <Field.Root> <div className="flex items-center gap-2"> <Switch.Root> <Switch.Thumb /> </Switch.Root> <Field.Label>Enable notifications</Field.Label> </div> </Field.Root> ``` ## Controlled ```tsx function ControlledSwitch() { const [enabled, setEnabled] = useState(false); return ( <Switch.Root checked={enabled} onCheckedChange={setEnabled}> <Switch.Thumb /> </Switch.Root> ); } ``` ## Disabled ```tsx <Switch.Root disabled> <Switch.Thumb /> </Switch.Root> ``` ## Compound Parts | Part | Description | |---|---| | `Switch.Root` | The switch track. Manages checked state and keyboard interaction. Changes background color when checked. | | `Switch.Thumb` | The sliding circle that moves between unchecked (`translate-x-0`) and checked (`translate-x-4`) positions. | ## Switch.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `checked` | `boolean` | -- | Controlled checked state | | `defaultChecked` | `boolean` | `false` | Initial checked state (uncontrolled) | | `onCheckedChange` | `(checked: boolean) => void` | -- | Called when the switch is toggled | | `disabled` | `boolean` | `false` | Disable the switch | | `className` | `string` | -- | Additional CSS classes | ## Switch.Thumb Props | Prop | Type | Default | Description | |---|---|---|---| | `className` | `string` | -- | Additional CSS classes | --- # Tabs A tabbed navigation component built on Base UI's `Tabs` primitive. Features an animated indicator that slides between active tabs using CSS transitions with the `ease-snappy` easing curve. ## Import ```tsx import { Tabs } from "chunks-ui"; ``` ## Basic Usage ```tsx <Tabs.Root defaultValue="tab-1"> <Tabs.List> <Tabs.Tab value="tab-1">Account</Tabs.Tab> <Tabs.Tab value="tab-2">Security</Tabs.Tab> <Tabs.Tab value="tab-3">Notifications</Tabs.Tab> <Tabs.Indicator /> </Tabs.List> <Tabs.Panel value="tab-1"> <p>Account settings content.</p> </Tabs.Panel> <Tabs.Panel value="tab-2"> <p>Security settings content.</p> </Tabs.Panel> <Tabs.Panel value="tab-3"> <p>Notification preferences.</p> </Tabs.Panel> </Tabs.Root> ``` ## Controlled ```tsx function ControlledTabs() { const [tab, setTab] = useState("overview"); return ( <Tabs.Root value={tab} onValueChange={setTab}> <Tabs.List> <Tabs.Tab value="overview">Overview</Tabs.Tab> <Tabs.Tab value="details">Details</Tabs.Tab> <Tabs.Indicator /> </Tabs.List> <Tabs.Panel value="overview">Overview content</Tabs.Panel> <Tabs.Panel value="details">Details content</Tabs.Panel> </Tabs.Root> ); } ``` ## Vertical Orientation Set `orientation="vertical"` on the root. The list switches to a vertical flex column with a right border: ```tsx <Tabs.Root defaultValue="tab-1" orientation="vertical"> <Tabs.List> <Tabs.Tab value="tab-1">General</Tabs.Tab> <Tabs.Tab value="tab-2">Advanced</Tabs.Tab> <Tabs.Indicator /> </Tabs.List> <Tabs.Panel value="tab-1">General settings</Tabs.Panel> <Tabs.Panel value="tab-2">Advanced settings</Tabs.Panel> </Tabs.Root> ``` ## Animated Indicator The `Tabs.Indicator` component renders an absolutely-positioned bar at the bottom of the active tab. It uses Base UI's built-in CSS variables (`--active-tab-left`, `--active-tab-width`) and transitions with `ease-snappy` for smooth sliding between tabs. The indicator works without JavaScript animation -- it relies purely on CSS transitions. ## Compound Parts | Part | Description | |---|---| | `Tabs.Root` | State container. Manages active tab value. | | `Tabs.List` | Horizontal (or vertical) container for tab triggers. Renders a border at the bottom. | | `Tabs.Tab` | Individual tab trigger button. Shows muted text by default, foreground text when active. | | `Tabs.Panel` | Content panel associated with a tab value. Shown when its tab is active. | | `Tabs.Indicator` | Animated bar that slides to the active tab position. | ## Tabs.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `string` | -- | Controlled active tab | | `defaultValue` | `string` | -- | Initial tab (uncontrolled) | | `onValueChange` | `(value: string) => void` | -- | Called when active tab changes | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction | | `className` | `string` | -- | Additional CSS classes | ## Tabs.Tab Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `string` | required | The value this tab represents | | `disabled` | `boolean` | `false` | Disable this tab | | `className` | `string` | -- | Additional CSS classes | --- # Textarea A multi-line text input with optional auto-resize behavior using the CSS `field-sizing: content` property. ## Import ```tsx import { Textarea } from "chunks-ui"; ``` ## Basic Usage ```tsx <Textarea placeholder="Write your message..." /> ``` ## Auto-Resize When `autoResize` is `true`, the textarea grows vertically to fit its content using the native CSS `field-sizing: content` property: ```tsx <Textarea autoResize placeholder="Start typing..." /> ``` The textarea has a `min-h-20` minimum height by default. ## With Field ```tsx <Field.Root> <Field.Label>Bio</Field.Label> <Field.Description>Write a short bio (max 280 characters)</Field.Description> <Textarea autoResize placeholder="Tell us about yourself..." maxLength={280} /> </Field.Root> ``` ## Disabled ```tsx <Textarea disabled placeholder="This field is disabled" /> ``` ## Props | Prop | Type | Default | Description | |---|---|---|---| | `autoResize` | `boolean` | `false` | Enable auto-resize via `field-sizing: content` | | `className` | `string` | -- | Additional CSS classes | All standard `<textarea>` props are supported (`value`, `onChange`, `placeholder`, `disabled`, `rows`, `maxLength`, etc.). --- # ThemeToggle A controlled button for switching between light and dark themes. Animates between sun and moon icons with a crossfade, and respects `prefers-reduced-motion`. ## Import ```tsx import { ThemeToggle } from "chunks-ui"; ``` ## Basic Usage `ThemeToggle` is fully controlled — pass the current `theme` and an `onClick` handler to toggle it: ```tsx function App() { const [theme, setTheme] = useState<"light" | "dark">("light"); return ( <ThemeToggle theme={theme} onClick={() => setTheme(theme === "light" ? "dark" : "light")} /> ); } ``` ## Custom Icons Replace the default sun/moon icons via `lightIcon` and `darkIcon`: ```tsx <ThemeToggle theme={theme} onClick={() => setTheme(theme === "light" ? "dark" : "light")} lightIcon={<SunIcon />} darkIcon={<MoonIcon />} /> ``` ## Props | Prop | Type | Default | Description | |---|---|---|---| | `theme` | `"light" \| "dark"` | required | Current active theme | | `onClick` | `React.MouseEventHandler<HTMLButtonElement>` | -- | Called when the button is clicked | | `lightIcon` | `React.ReactNode` | Built-in sun SVG | Icon shown in light mode | | `darkIcon` | `React.ReactNode` | Built-in moon SVG | Icon shown in dark mode | | `className` | `string` | -- | Additional CSS classes | --- # Toast A notification system built on Base UI's `Toast` primitive. Toasts slide in from the bottom-right corner and auto-dismiss. The `useToast` hook triggers them from anywhere within the provider. ## Import ```tsx import { Toast } from "chunks-ui"; ``` ## Setup Wrap your app (or the relevant subtree) with `Toast.Provider` and place `Toast.Viewport` where the toasts should render: ```tsx export default function RootLayout({ children }) { return ( <Toast.Provider> {children} <Toast.Viewport /> </Toast.Provider> ); } ``` ## Basic Usage Use `Toast.useToast()` to get the `add` function and trigger notifications: ```tsx function SaveButton() { const { add } = Toast.useToast(); return ( <button onClick={() => add({ title: "Saved", description: "Your changes have been saved." })}> Save </button> ); } ``` ## Multiple Toasts Multiple toasts stack in the viewport. Each call to `add` creates an independent toast: ## With Action Pass `actionProps` to render a labelled action button inside the toast: ```tsx const { add } = Toast.useToast(); add({ title: "Message deleted", description: "The message has been removed from your inbox.", actionProps: { children: "Undo", onClick: () => restoreMessage(), }, }); ``` ## Compound Parts | Part | Description | |---|---| | `Toast.Provider` | Context provider. Must wrap any component that calls `useToast`. | | `Toast.Viewport` | Fixed-position container that renders all active toasts. | | `Toast.Root` | Individual toast wrapper with slide/fade enter/exit transitions. | | `Toast.Title` | Bold toast heading. | | `Toast.Description` | Supporting text in `text-muted-foreground`. | | `Toast.Close` | Icon button that dismisses the toast. | | `Toast.Action` | Optional action button rendered inside the toast. | | `Toast.useToast` | Hook that returns `{ add, toasts }` for the nearest provider. | ## Toast.useToast — `add` Options | Option | Type | Description | |---|---|---| | `title` | `string` | Toast heading text | | `description` | `string` | Supporting body text | | `actionProps` | `{ children: ReactNode; onClick: () => void }` | Props for the action button | | `timeout` | `number` | Auto-dismiss delay in milliseconds (provider default applies if omitted) | ## Toast.Provider Props | Prop | Type | Default | Description | |---|---|---|---| | `timeout` | `number` | `5000` | Default auto-dismiss delay in ms | | `limit` | `number` | -- | Maximum number of toasts shown simultaneously | ## Toast.Viewport Props | Prop | Type | Default | Description | |---|---|---|---| | `className` | `string` | -- | Additional CSS classes on the viewport container | --- # Toggle Group A group of toggle buttons where one or multiple items can be pressed at a time. Built on Base UI's `Toggle` and `ToggleGroup` primitives. In single-select mode, a sliding indicator animates between the active item using Motion (with CSS transition fallback). ## Import ```tsx import { ToggleGroup } from "chunks-ui"; ``` ## Basic Usage By default, the toggle group operates in single-select mode. Only one item can be pressed at a time, and a sliding indicator highlights the active selection: ```tsx <ToggleGroup.Root defaultValue={["bold"]}> <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item> <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item> <ToggleGroup.Item value="underline">Underline</ToggleGroup.Item> </ToggleGroup.Root> ``` ## Multiple Selection Set `multiple` to allow pressing more than one item at a time. Each pressed item gets its own background highlight instead of a shared sliding indicator: ```tsx <ToggleGroup.Root multiple defaultValue={["bold", "italic"]}> <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item> <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item> <ToggleGroup.Item value="underline">Underline</ToggleGroup.Item> </ToggleGroup.Root> ``` ## Controlled ```tsx function ControlledToggleGroup() { const [value, setValue] = useState(["bold"]); return ( <ToggleGroup.Root value={value} onValueChange={setValue}> <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item> <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item> <ToggleGroup.Item value="underline">Underline</ToggleGroup.Item> </ToggleGroup.Root> ); } ``` ## Compound Parts | Part | Description | |---|---| | `ToggleGroup.Root` | Container that manages selection state. Renders a pill-shaped muted background with inline-flex layout. In single-select mode, renders a sliding indicator behind the active item. | | `ToggleGroup.Item` | Individual toggle button. Shows muted text by default, foreground text when pressed. In multiple mode, each pressed item gets its own background highlight. | ## ToggleGroup.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `unknown[]` | -- | Controlled pressed values | | `defaultValue` | `unknown[]` | `[]` | Initial pressed values (uncontrolled) | | `onValueChange` | `(value: unknown[]) => void` | -- | Called when the pressed state changes | | `multiple` | `boolean` | `false` | Allow multiple items to be pressed at once | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction | | `disabled` | `boolean` | `false` | Disable all toggle items | | `className` | `string` | -- | Additional CSS classes | ## ToggleGroup.Item Props | Prop | Type | Default | Description | |---|---|---|---| | `value` | `unknown` | required | The value this item represents | | `disabled` | `boolean` | `false` | Disable this toggle item | | `className` | `string` | -- | Additional CSS classes | --- # Tooltip A hover/focus tooltip built on Base UI's `Tooltip` primitive. Automatically positioned via Floating UI with a scale/fade transition. ## Import ```tsx import { Tooltip } from "chunks-ui"; ``` ## Basic Usage ```tsx <Tooltip.Root> <Tooltip.Trigger> <button>Hover me</button> </Tooltip.Trigger> <Tooltip.Portal> <Tooltip.Positioner> <Tooltip.Popup>Helpful tip</Tooltip.Popup> </Tooltip.Positioner> </Tooltip.Portal> </Tooltip.Root> ``` ## With Arrow ```tsx <Tooltip.Root> <Tooltip.Trigger> <button>Info</button> </Tooltip.Trigger> <Tooltip.Portal> <Tooltip.Positioner> <Tooltip.Popup> <Tooltip.Arrow /> This is a tooltip with an arrow. </Tooltip.Popup> </Tooltip.Positioner> </Tooltip.Portal> </Tooltip.Root> ``` ## Tooltip Provider Use `Tooltip.Provider` to share delay settings across multiple tooltips. This avoids delays when moving between nearby tooltips: ```tsx <Tooltip.Provider delay={200} closeDelay={0}> <Tooltip.Root> <Tooltip.Trigger><button>A</button></Tooltip.Trigger> <Tooltip.Portal> <Tooltip.Positioner> <Tooltip.Popup>Tooltip A</Tooltip.Popup> </Tooltip.Positioner> </Tooltip.Portal> </Tooltip.Root> <Tooltip.Root> <Tooltip.Trigger><button>B</button></Tooltip.Trigger> <Tooltip.Portal> <Tooltip.Positioner> <Tooltip.Popup>Tooltip B</Tooltip.Popup> </Tooltip.Positioner> </Tooltip.Portal> </Tooltip.Root> </Tooltip.Provider> ``` ## Positioning The positioner has a default `sideOffset` of `6px`. Override placement with `side` and `align`: ```tsx <Tooltip.Positioner side="right" align="center"> <Tooltip.Popup>Right-aligned tooltip</Tooltip.Popup> </Tooltip.Positioner> ``` ## Compound Parts | Part | Description | |---|---| | `Tooltip.Root` | State container. Manages hover/focus open state. | | `Tooltip.Trigger` | The element that activates the tooltip on hover/focus. | | `Tooltip.Portal` | Renders children in a portal. | | `Tooltip.Positioner` | Floating UI positioner. Default `sideOffset={6}`. | | `Tooltip.Popup` | The tooltip content. Dark background (`bg-foreground`), light text (`text-background`). `z-tooltips` (400). | | `Tooltip.Arrow` | A rotated square (`bg-foreground`) absolutely positioned at the popup edge. Aligned to the anchor via Base UI CSS variables. | | `Tooltip.Provider` | Shared delay configuration for grouped tooltips. | ## Tooltip.Root Props | Prop | Type | Default | Description | |---|---|---|---| | `open` | `boolean` | -- | Controlled open state | | `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) | | `onOpenChange` | `(open: boolean) => void` | -- | Called when open state changes | | `delay` | `number` | `600` | Milliseconds before showing | | `closeDelay` | `number` | `0` | Milliseconds before hiding | ---