# Changelog (/docs/changelog)

## July 2026 - Base UI [#july-2026---base-ui]

ui-x is now built on [Base UI](https://base-ui.com). Following shadcn/ui's adoption of Base UI as the modern successor to Radix UI, every component has been rebuilt on Base UI primitives and restyled to match the latest shadcn/ui design.

<ComponentPreview name="date-picker-demo" />

### What's changed [#whats-changed]

* **Base UI everywhere** — All Radix UI dependencies are gone. Components are built on Base UI primitives and utilities, with React 19 ref handling throughout.
* **Restyled** — Every component, demo and docs page has been refreshed against the latest shadcn/ui styling.
* **Simpler forms** — Demos use Base UI's `Field` and `Form` for form plumbing. For React Hook Form or TanStack Form wiring, see the shadcn/ui [forms guides](https://ui.shadcn.com/docs/forms).
* **Dropzone composes with Empty** — `DropzoneGroup`, `DropzoneTitle` and `DropzoneDescription` are gone. Build the zone's title and description with shadcn/ui's [Empty](https://ui.shadcn.com/docs/components/empty) component instead; `DropzoneUploadIcon` stays for the drag-state icon swap.

### Superseded components [#superseded-components]

shadcn/ui now ships first-class versions of several components that ui-x originally existed to fill in. These have been removed in favor of the official ones:

| ui-x component | Use instead                                                          |
| -------------- | -------------------------------------------------------------------- |
| Calendar       | [Calendar](https://ui.shadcn.com/docs/components/calendar)           |
| Combobox       | [Combobox](https://ui.shadcn.com/docs/components/combobox)           |
| Control Group  | [Button Group](https://ui.shadcn.com/docs/components/button-group)   |
| File List      | [Attachment](https://ui.shadcn.com/docs/components/attachment)       |
| Input Base     | [Input Group](https://ui.shadcn.com/docs/components/input-group)     |
| Kbd            | [Kbd](https://ui.shadcn.com/docs/components/kbd)                     |
| Native Select  | [Native Select](https://ui.shadcn.com/docs/components/native-select) |

## June 2025 - Phone Input and Emoji Picker [#june-2025---phone-input-and-emoji-picker]

We've added a new `<PhoneInput />` component and a new `<EmojiPicker />` component.

### Phone Input [#phone-input]

A component for phone number input field with country selection and formatting. Built on top of [react-phone-number-input](https://github.com/catamphetamine/react-phone-number-input).

<ComponentPreview name="phone-input-demo" />

[Read the docs](/docs/components/phone-input)

### Emoji Picker [#emoji-picker]

A component that allows users to select an emoji from a list of emojis. Built on top of [frimousse](https://frimousse.liveblocks.io/).

<ComponentPreview name="emoji-picker-demo" />

[Read the docs](/docs/components/emoji-picker)

## May 2025 - Tailwind v4 and React 19 [#may-2025---tailwind-v4-and-react-19]

We're excited to announce support for Tailwind v4 and React 19! This major update brings significant improvements and new features to the UI components library. Please refer to shadcn/ui's [Tailwind v4](https://ui.shadcn.com/docs/tailwind-v4) documentation for more details on migrating your project and taking advantage of the new capabilities.

### Wheel Picker [#wheel-picker]

Along with this major update, we've also added a new `<WheelPicker />` component, built on top of [react-wheel-picker](https://github.com/ncdai/react-wheel-picker). This component provides an iOS-like interface for selecting options from a scrollable wheel.

<ComponentPreview name="wheel-picker-demo" />

[Read the docs](/docs/components/wheel-picker)

## February 2025 - Virtualizer [#february-2025---virtualizer]

We've added a new Virtualizer documentation page.

### Virtualizer [#virtualizer]

Learn how to use the `virtua` library to efficiently render large lists and grids by virtualizing your components. This documentation provides practical examples and guidance on integrating `virtua` with your existing components.

<ComponentPreview name="virtualized-demo" />

[Read the docs](/docs/utilities/virtualized)

## February 2025 - Sortable and Control Group [#february-2025---sortable-and-control-group]

We've added a new `<Sortable />` component and a new `<ControlGroup />` component.

### Sortable [#sortable]

A drag and drop component for reordering items in a list or grid. `<Sortable />` is built on top of [@dnd-kit](https://dndkit.com)'s [sortable](https://docs.dndkit.com/presets/sortable) preset.

<ComponentPreview name="sortable-demo" />

[See more examples](/docs/utilities/sortable)

### Control Group [#control-group]

A component for grouping form controls like text inputs, buttons, selects and other elements into a single cohesive unit. When used together with Input Base, you can create highly customizable and flexible input layouts for a variety of use cases. Control Group has since been superseded by shadcn/ui's [Button Group](https://ui.shadcn.com/docs/components/button-group).

### Thank you [#thank-you]

I'd like to thank everyone who has been using this project, providing feedback and contributing to it. I really appreciate it. Thank you 🙏

# Introduction (/docs)

**Similar to shadcn/ui, this is not a component library, It is how you build your component library.**

junwen-k/ui-x is a thoughtfully crafted extension that provides additional components while maintaining the same principles of being open, composable and customizable.

As junwen-k/ui-x is built as an extension of shadcn/ui, it inherits the core philosophies and approaches. For the foundational concepts, please refer to shadcn/ui's [documentation](https://ui.shadcn.com/docs).

## Philosophy [#philosophy]

The components in this extension are built around four key principles:

* **Intuitive Developer Experience:** Each component's API mirrors Base UI conventions and shadcn/ui patterns, creating an intuitive and familiar experience.
* **Natural Extension:** Components are thoughtfully designed to feel like natural additions to the shadcn/ui ecosystem, maintaining the same level of quality and coherence.
* **Open and Customizable:** Like shadcn/ui, you have full access to the component code, allowing complete customization to fit your needs.
* **AI-Ready:** Components are designed to be compatible with AI tools like [v0](https://v0.dev), enabling seamless integration with AI-powered development workflows.

## Acknowledgments [#acknowledgments]

This project stands on the shoulders of amazing open source projects and many other incredible libraries. Thank you to all the maintainers and contributors who make this extension possible.

## FAQ [#faq]

<Accordion type="multiple">
  <AccordionItem value="faq-1">
    <AccordionTrigger>
      How does it integrate with shadcn/ui?
    </AccordionTrigger>

    <AccordionContent>
      The components are designed to work seamlessly with shadcn's design system
      and distribution approach. They integrate naturally with your existing
      shadcn/ui components while maintaining consistent styling, behavior, and
      developer experience.
    </AccordionContent>
  </AccordionItem>

  <AccordionItem value="faq-2">
    <AccordionTrigger>
      Why are there additional primitives?
    </AccordionTrigger>

    <AccordionContent>
      This extension includes additional primitive components for features not
      covered by Base UI. By maintaining the separation between primitive logic
      and styled components, we ensure cleaner code and better maintainability
      while expanding the available functionality.
    </AccordionContent>
  </AccordionItem>
</Accordion>

# Installation (/docs/installation)

junwen-k/ui-x is an extension of [shadcn/ui](https://ui.shadcn.com) and is distributed through the same registry system. Set up shadcn/ui in your project first by following the official [installation guide](https://ui.shadcn.com/docs/installation) for your framework.

## Requirements [#requirements]

* A project set up with [shadcn/ui](https://ui.shadcn.com/docs/installation) (Tailwind CSS v4 and React 19 for the latest components). The Tailwind v3 docs are no longer maintained and remain archived at [v3-ui-x.junwen-k.dev](https://v3-ui-x.junwen-k.dev).
* Components are built on [Base UI](https://base-ui.com) primitives, matching shadcn/ui's Base UI-based components.

## Installing components [#installing-components]

Every component can be installed with the shadcn CLI by pointing at this registry:

```bash
npx shadcn@latest add junwen-k/ui-x/date-field
```

Each component's documentation page includes its exact install command, along with a manual installation option if you prefer to copy the source directly.

## Utilities [#utilities]

Utility docs such as [Sortable](/docs/utilities/sortable) and [Virtualized](/docs/utilities/virtualized) are guides built around third-party libraries — their pages describe which packages to install.

# Badge Group (/docs/components/badge-group)

<ComponentPreview name="badge-group-demo" />

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/badge-group
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui/react @base-ui/utils
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="badge-group" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import { BadgeGroup, BadgeGroupItem } from "@/components/ui/badge-group";
```

```tsx
<BadgeGroup type="single">
  <BadgeGroupItem value="chocolate">Chocolate</BadgeGroupItem>
  <BadgeGroupItem value="mint">Mint</BadgeGroupItem>
  <BadgeGroupItem value="strawberry">Strawberry</BadgeGroupItem>
  <BadgeGroupItem value="vanilla">Vanilla</BadgeGroupItem>
</BadgeGroup>
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="badge-group-demo" />

### Form [#form]

<ComponentPreview name="badge-group-form" />

## Accessibility [#accessibility]

The group is built on [Base UI Toggle Group](https://base-ui.com/react/components/toggle-group): one item is tabbable at a time, the arrow keys move focus between items, and <Kbd>Space</Kbd> or <Kbd>Enter</Kbd> toggles the focused item. When removal is enabled, <Kbd>Backspace</Kbd> and <Kbd>Delete</Kbd> remove the focused item — the close icon is a pointer-only affordance hidden from assistive technology, so keyboard and screen-reader users are not dependent on it.

## API Reference [#api-reference]

### BadgeGroup [#badgegroup]

The group container. Renders a [Base UI Toggle Group](https://base-ui.com/react/components/toggle-group).

| Prop            | Type                     | Default    | Description                                                                                                                                    |
| --------------- | ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`          | `"single" \| "multiple"` | `"single"` | Whether one or several items can be pressed at a time. Determines the value type below.                                                        |
| `value`         | `string \| string[]`     | -          | The pressed item(s), typed by `type`. Use for controlled value.                                                                                |
| `defaultValue`  | `string \| string[]`     | -          | The initial value when uncontrolled.                                                                                                           |
| `onValueChange` | `(value) => void`        | -          | Called when the pressed item(s) change. The value is typed by `type`.                                                                          |
| `onRemove`      | `(value) => void`        | -          | Enables removal. Called with the removed value(s) when an item's close icon is clicked or <Kbd>Backspace</Kbd> / <Kbd>Delete</Kbd> is pressed. |
| `...props`      | `ToggleGroup.Props`      | -          | Remaining props are spread to [Base UI Toggle Group](https://base-ui.com/react/components/toggle-group#api-reference).                         |

### BadgeGroupItem [#badgegroupitem]

A single badge. Renders a [Base UI Toggle](https://base-ui.com/react/components/toggle) styled as an outline [Badge](https://ui.shadcn.com/docs/components/badge). Shows a close icon when the group has `onRemove`.

| Prop       | Type           | Default | Description                                                                                                |
| ---------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| `value`    | `string`       | -       | The item's value within the group. Required.                                                               |
| `...props` | `Toggle.Props` | -       | Remaining props are spread to [Base UI Toggle](https://base-ui.com/react/components/toggle#api-reference). |

# Confirmer (/docs/components/confirmer)

<ComponentPreview name="confirmer-demo" />

## About [#about]

The `<Confirmer />` component is built on top of [react-call](https://react-call.desko.dev/).

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <Steps>
      <Step>
        Run the following command:
      </Step>

      ```bash
      npx shadcn@latest add junwen-k/ui-x/confirmer
      ```

      <Step>
        Add the `<Confirmer />` component.
      </Step>

      ```tsx title="app/layout.tsx" showLineNumbers {1,9}
      import { Confirmer } from "@/components/ui/confirmer";

      export default function RootLayout({ children }) {
        return (
          <html lang="en">
            <head />
            <body>
              <main>{children}</main>
              <Confirmer />
            </body>
          </html>
        );
      }
      ```
    </Steps>
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install react-call
      ```

      <Step>
        Add the `<AlertDialog />` and `<Button />` component to your project.
      </Step>

      The `<Confirmer />` component uses `<AlertDialog />` and `<Button />` components. Make sure you have it installed in your project.

      See installation instructions for the [AlertDialog](https://ui.shadcn.com/docs/components/alert-dialog) and the [Button](https://ui.shadcn.com/docs/components/button) components.

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="confirmer" />

      <Step>
        Update the import paths to match your project setup.
      </Step>

      <Step>
        Add the `<Confirmer />` component.
      </Step>

      ```tsx title="app/layout.tsx" showLineNumbers {1,9}
      import { Confirmer } from "@/components/ui/confirmer";

      export default function RootLayout({ children }) {
        return (
          <html lang="en">
            <head />
            <body>
              <main>{children}</main>
              <Confirmer />
            </body>
          </html>
        );
      }
      ```
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import { confirm } from "@/components/ui/confirmer";
```

```tsx
confirm({
  title: "Are you absolutely sure?",
  description:
    "This action cannot be undone. This will permanently delete your account and remove your data from our servers.",
}).then((confirmed) => {
  // ...
});
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="confirmer-demo" />

## Accessibility [#accessibility]

`<Confirmer />` renders an `<AlertDialog />`, so it inherits Base UI's alert dialog semantics: the dialog traps focus while open, labels itself from `<AlertDialogTitle>` and `<AlertDialogDescription>` (the `title` and `description` options), and returns focus to the triggering element when it closes.

Pressing <Kbd>Escape</Kbd> or activating the cancel button resolves `confirm()` with `false`, mirroring a dismissed dialog. Always pass a `title` (and a `description` for anything non-obvious) so screen reader users hear what they're confirming, and set `ActionProps={{ variant: "destructive" }}` rather than color alone to distinguish destructive actions.

## API Reference [#api-reference]

### Confirmer [#confirmer]

The dialog host. Render it once near the root of your app; it renders nothing until `confirm` is called. Takes no props.

### confirm [#confirm]

Opens the confirm dialog imperatively and resolves with the user's choice — `true` for the action button, `false` for cancel or dismissing the dialog.

```tsx
function confirm(options?: ConfirmOptions): Promise<boolean>;
```

| Option        | Type                                             | Default           | Description                                                                                         |
| ------------- | ------------------------------------------------ | ----------------- | --------------------------------------------------------------------------------------------------- |
| `title`       | `ReactNode`                                      | `"Are you sure?"` | The dialog title.                                                                                   |
| `description` | `ReactNode`                                      | -                 | The dialog description.                                                                             |
| `cancelText`  | `ReactNode`                                      | `"Cancel"`        | The cancel button label.                                                                            |
| `actionText`  | `ReactNode`                                      | `"Continue"`      | The action button label.                                                                            |
| `CancelProps` | `React.ComponentProps<typeof AlertDialogCancel>` | -                 | Props spread to the cancel button.                                                                  |
| `ActionProps` | `React.ComponentProps<typeof AlertDialogAction>` | -                 | Props spread to the action button, e.g. `{ variant: "destructive" }` for destructive confirmations. |

# Date Field (/docs/components/date-field)

<ComponentPreview name="date-field-demo" />

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/date-field
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Add `<DateTimeField />` component to your project.
      </Step>

      The `<TimeField />` component uses the `<DateTimeField />` component. Make sure you have it installed in your project.

      See installation instructions for the [DateTimeField](/docs/components/date-time-field#installation) component.

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="date-field" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import {
  DateField,
  DateFieldDays,
  DateFieldMonths,
  DateFieldSeparator,
  DateFieldYears,
} from "@/components/ui/date-field";
```

```tsx
<DateField>
  <DateFieldDays />
  <DateFieldSeparator />
  <DateFieldMonths />
  <DateFieldSeparator />
  <DateFieldYears />
</DateField>
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="date-field-demo" />

### Form [#form]

<ComponentPreview name="date-field-form" />

## Accessibility [#accessibility]

The field follows the segment keyboard model and labeling guidance described in the [Date Time Field accessibility](/docs/components/date-time-field#accessibility) section.

## API Reference [#api-reference]

A date-only preset of the [Date Time Field](/docs/components/date-time-field#api-reference) — each part wraps its Date Time Field counterpart and accepts the same props.

### DateField [#datefield]

Wraps `DateTimeField` and accepts all of the [Root props](/docs/primitives/date-time-field#root) (`value`, `onValueChange`, `minDate`, `maxDate`, …).

### DateFieldDays, DateFieldMonths, DateFieldYears [#datefielddays-datefieldmonths-datefieldyears]

Wrap the corresponding [segments](/docs/primitives/date-time-field#segments) with their default placeholders (`dd`, `mm`, `yyyy`).

### DateFieldSeparator [#datefieldseparator]

Wraps the [separator](/docs/components/date-time-field#datetimefieldseparator) with `/` as the default children.

# Date Picker (/docs/components/date-picker)

<ComponentPreview name="date-picker-demo" />

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/date-picker
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Add the `<Button />`, `<Calendar />`, `<DateField />`, `<DatePickerPrimitive />` and `<InputGroup />` component to your project.
      </Step>

      The `<DatePicker />` component uses `<Button />`, `<Calendar />`, `<DateField />`, `<DatePickerPrimitive />` and `<InputGroup />` components. Make sure you have it installed in your project.

      See installation instructions for the [Button](https://ui.shadcn.com/docs/components/button), [Calendar](https://ui.shadcn.com/docs/components/calendar), [DateField](/docs/components/date-field#installation), [DatePickerPrimitive](/docs/primitives/date-picker#installation) and the [Input Group](https://ui.shadcn.com/docs/components/input-group) components.

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="date-picker" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Examples [#examples]

### Date Picker [#date-picker]

<ComponentPreview name="date-picker-demo" />

### Input [#input]

<ComponentPreview name="date-picker-input" />

### Form [#form]

<ComponentPreview name="date-picker-form" />

## Accessibility [#accessibility]

### Labeling [#labeling]

The trigger and clear buttons in the input variant are icon-only. `<DatePickerInput />` ships a visually hidden "Clear date" label for the clear button; when composing your own icon-only triggers, give them an accessible name with `aria-label` or a visually hidden `<span className="sr-only">`.

### Keyboard interactions [#keyboard-interactions]

The inline date field follows the segment keyboard model described in the [Date Time Field accessibility](/docs/components/date-time-field#accessibility) section. Inside the popover, the calendar supports the arrow keys to move between days, <Kbd>PageUp</Kbd> / <Kbd>PageDown</Kbd> to change months and <Kbd>Enter</Kbd> to select. <Kbd>Escape</Kbd> closes the popover and returns focus to the trigger.

## API Reference [#api-reference]

Styled wrappers around the [Date Picker primitive](/docs/primitives/date-picker#api-reference). Each part forwards its props to the primitive part it wraps — see the primitive page for the full prop tables.

### DatePicker [#datepicker]

Wraps [Root](/docs/primitives/date-picker#root) and accepts all of its props (`mode`, `value`, `onValueChange`, `formatStr`, `month`, `required`, `disabled`, …).

### DatePickerTrigger [#datepickertrigger]

Wraps [Trigger](/docs/primitives/date-picker#trigger), rendered as an outline `<Button />` with a calendar icon.

### DatePickerValue [#datepickervalue]

Wraps [Value](/docs/primitives/date-picker#value), muting the placeholder text. Accepts `placeholder`.

### DatePickerInput [#datepickerinput]

An [Input Group](https://ui.shadcn.com/docs/components/input-group) containing the inline date field plus clear and open buttons. Renders a single-date field or a range field automatically based on the root's `mode`; the inline field is not supported in `"multiple"` mode. Accepts the corresponding [DateField / DateRangeField props](/docs/primitives/date-picker#datefield).

### DatePickerAnchor [#datepickeranchor]

Wraps [Anchor](/docs/primitives/date-picker#anchor) for positioning the popover against a custom element.

### DatePickerContent [#datepickercontent]

Wraps [Portal, Positioner and Content](/docs/primitives/date-picker#portal-positioner-content) with popover styling, and lifts the common positioning props.

| Prop          | Type                                     | Default    | Description                                 |
| ------------- | ---------------------------------------- | ---------- | ------------------------------------------- |
| `align`       | `"start" \| "center" \| "end"`           | `"start"`  | Alignment against the anchor.               |
| `alignOffset` | `number`                                 | `4`        | Offset along the alignment axis.            |
| `side`        | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Side of the anchor to render against.       |
| `sideOffset`  | `number`                                 | `0`        | Distance from the anchor.                   |
| `...props`    | `Content props`                          | -          | Remaining props spread to the content part. |

### DatePickerCalendar [#datepickercalendar]

Wraps [Calendar](/docs/primitives/date-picker#calendar), rendering the styled [Calendar](https://ui.shadcn.com/docs/components/calendar) component. Accepts the styled calendar's props.

# Date Time Field (/docs/components/date-time-field)

<ComponentPreview name="date-time-field-demo" />

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/date-time-field
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Add `<DateTimeFieldPrimitive />` and `<InputGroup />` component to your project.
      </Step>

      The `<DateTimeField />` component uses `<DateTimeFieldPrimitive />` and `<InputGroup />` components. Make sure you have it installed in your project.

      See installation instructions for the [DateTimeFieldPrimitive](/docs/primitives/date-time-field#installation) and [Input Group](https://ui.shadcn.com/docs/components/input-group) components.

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="date-time-field" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import {
  DateTimeField,
  DateTimeFieldAmPm,
  DateTimeFieldDays,
  DateTimeFieldHours,
  DateTimeFieldMinutes,
  DateTimeFieldMonths,
  DateTimeFieldSeconds,
  DateTimeFieldSeparator,
  DateTimeFieldYears,
} from "@/components/ui/date-time-field";
```

```tsx
<DateTimeField>
  <DateTimeFieldDays />
  <DateTimeFieldSeparator>/</DateTimeFieldSeparator>
  <DateTimeFieldMonths />
  <DateTimeFieldSeparator>/</DateTimeFieldSeparator>
  <DateTimeFieldYears />
  <DateTimeFieldSeparator>·</DateTimeFieldSeparator>
  <DateTimeFieldHours />
  <DateTimeFieldSeparator>:</DateTimeFieldSeparator>
  <DateTimeFieldMinutes />
  <DateTimeFieldSeparator>:</DateTimeFieldSeparator>
  <DateTimeFieldSeconds />
  <DateTimeFieldAmPm />
</DateTimeField>
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="date-time-field-demo" />

### Form [#form]

<ComponentPreview name="date-time-field-form" />

## Accessibility [#accessibility]

### Labeling [#labeling]

Each segment is an individual `<input>`, so the field needs a group label: associate a visible label with the field (for example via `<Field>` and `<FieldLabel>` in forms), or label the group with `aria-labelledby`. Separators are decorative and hidden from assistive technology with `aria-hidden`.

### Keyboard interactions [#keyboard-interactions]

| Key                                        | Description                                                          |
| ------------------------------------------ | -------------------------------------------------------------------- |
| <Kbd>ArrowLeft</Kbd> <Kbd>ArrowRight</Kbd> | Moves focus to the previous / next segment.                          |
| <Kbd>ArrowUp</Kbd> <Kbd>ArrowDown</Kbd>    | Increments / decrements the focused segment.                         |
| <Kbd>0</Kbd>–<Kbd>9</Kbd>                  | Types a value into the segment, advancing to the next when complete. |
| <Kbd>A</Kbd> <Kbd>P</Kbd>                  | Sets the meridiem segment to AM / PM.                                |
| <Kbd>Backspace</Kbd> <Kbd>Delete</Kbd>     | Clears the focused segment.                                          |

## API Reference [#api-reference]

Styled wrappers around the [Date Time Field primitive](/docs/primitives/date-time-field#api-reference) — see the primitive page for the full prop tables.

### DateTimeField [#datetimefield]

Wraps [Root](/docs/primitives/date-time-field#root) and accepts all of its props (`value`, `onValueChange`, `hour12`, `minDate`, `maxDate`, …), rendered as an [Input Group](https://ui.shadcn.com/docs/components/input-group).

### DateTimeFieldDays, DateTimeFieldMonths, DateTimeFieldYears, DateTimeFieldHours, DateTimeFieldMinutes, DateTimeFieldSeconds [#datetimefielddays-datetimefieldmonths-datetimefieldyears-datetimefieldhours-datetimefieldminutes-datetimefieldseconds]

Wrap the corresponding [segments](/docs/primitives/date-time-field#segments) with input styling and default placeholders (`dd`, `mm`, `yyyy` and `--` for the time segments).

### DateTimeFieldAmPm [#datetimefieldampm]

Wraps [AmPm](/docs/primitives/date-time-field#ampm); renders only when the field has `hour12`.

### DateTimeFieldSeparator [#datetimefieldseparator]

Wraps [Separator](/docs/primitives/date-time-field#separator) with muted styling. Pass the separator character as `children` (e.g. `/` or `:`).

# Date Time Range Field (/docs/components/date-time-range-field)

<ComponentPreview name="date-time-range-field-demo" />

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/date-time-range-field
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Add `<DateTimeField />`, `<DateTimeRangeFieldPrimitive />` and `<InputGroup />` component to your project.
      </Step>

      The `<DateTimeRangeField />` component uses `<DateTimeField />`, `<DateTimeRangeFieldPrimitive />` and `<InputGroup />` components. Make sure you have it installed in your project.

      See installation instructions for the [DateTimeField](/docs/components/date-time-field#installation), [DateTimeRangeFieldPrimitive](/docs/primitives/date-time-range-field#installation), [Input Group](https://ui.shadcn.com/docs/components/input-group) components.

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="date-time-range-field" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import {
  DateTimeRangeField,
  DateTimeRangeFieldAmPm,
  DateTimeRangeFieldDays,
  DateTimeRangeFieldFrom,
  DateTimeRangeFieldHours,
  DateTimeRangeFieldMinutes,
  DateTimeRangeFieldMonths,
  DateTimeRangeFieldSeconds,
  DateTimeRangeFieldSeparator,
  DateTimeRangeFieldTo,
  DateTimeRangeFieldYears,
} from "@/components/ui/date-time-range-field";
```

```tsx
<DateTimeRangeField>
  <DateTimeRangeFieldFrom>
    <DateTimeRangeFieldDays />
    <DateTimeRangeFieldSeparator>/</DateTimeRangeFieldSeparator>
    <DateTimeRangeFieldMonths />
    <DateTimeRangeFieldSeparator>/</DateTimeRangeFieldSeparator>
    <DateTimeRangeFieldYears />
    <DateTimeRangeFieldSeparator>·</DateTimeRangeFieldSeparator>
    <DateTimeRangeFieldHours />
    <DateTimeRangeFieldSeparator>:</DateTimeRangeFieldSeparator>
    <DateTimeRangeFieldMinutes />
    <DateTimeRangeFieldSeparator>:</DateTimeRangeFieldSeparator>
    <DateTimeRangeFieldSeconds />
    <DateTimeRangeFieldAmPm />
  </DateTimeRangeFieldFrom>

  <DateTimeRangeFieldSeparator>-</DateTimeRangeFieldSeparator>

  <DateTimeRangeFieldTo>
    <DateTimeRangeFieldDays />
    <DateTimeRangeFieldSeparator>/</DateTimeRangeFieldSeparator>
    <DateTimeRangeFieldMonths />
    <DateTimeRangeFieldSeparator>/</DateTimeRangeFieldSeparator>
    <DateTimeRangeFieldYears />
    <DateTimeRangeFieldSeparator>·</DateTimeRangeFieldSeparator>
    <DateTimeRangeFieldHours />
    <DateTimeRangeFieldSeparator>:</DateTimeRangeFieldSeparator>
    <DateTimeRangeFieldMinutes />
    <DateTimeRangeFieldSeparator>:</DateTimeRangeFieldSeparator>
    <DateTimeRangeFieldSeconds />
    <DateTimeRangeFieldAmPm />
  </DateTimeRangeFieldTo>
</DateTimeRangeField>
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="date-time-range-field-demo" />

### Form [#form]

<ComponentPreview name="date-time-range-field-form" />

## Accessibility [#accessibility]

The field follows the segment keyboard model and labeling guidance described in the [Date Time Field accessibility](/docs/components/date-time-field#accessibility) section. Since the range spans two groups of segments, prefer one visible label for the whole field, or label the `From` and `To` groups individually with `aria-label` when they need distinct names.

## API Reference [#api-reference]

Styled wrappers around the [Date Time Range Field primitive](/docs/primitives/date-time-range-field#api-reference) — see the primitive page for the full prop tables.

### DateTimeRangeField [#datetimerangefield]

Wraps [Root](/docs/primitives/date-time-range-field#root) and accepts all of its props (`value`, `onValueChange`, `hour12`, `from`, `to`, …), rendered as an [Input Group](https://ui.shadcn.com/docs/components/input-group).

### DateTimeRangeFieldFrom, DateTimeRangeFieldTo [#datetimerangefieldfrom-datetimerangefieldto]

Wrap [From and To](/docs/primitives/date-time-range-field#from-to). Segments must be placed inside one of the two.

### DateTimeRangeFieldDays, DateTimeRangeFieldMonths, DateTimeRangeFieldYears, DateTimeRangeFieldHours, DateTimeRangeFieldMinutes, DateTimeRangeFieldSeconds [#datetimerangefielddays-datetimerangefieldmonths-datetimerangefieldyears-datetimerangefieldhours-datetimerangefieldminutes-datetimerangefieldseconds]

Wrap the corresponding [segments](/docs/primitives/date-time-range-field#segments), rendered with the [Date Time Field](/docs/components/date-time-field#api-reference) segment styling and placeholders.

### DateTimeRangeFieldAmPm [#datetimerangefieldampm]

Wraps [AmPm](/docs/primitives/date-time-range-field#ampm); renders only when its field has `hour12`.

### DateTimeRangeFieldSeparator [#datetimerangefieldseparator]

Wraps the styled [Date Time Field separator](/docs/components/date-time-field#datetimefieldseparator). Pass the separator character as `children` (e.g. `/`, `:` or `-` between the two fields).

# Description List (/docs/components/description-list)

<ComponentPreview name="description-list-demo" />

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/description-list
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="description-list" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import {
  DescriptionDetail,
  DescriptionGroup,
  DescriptionList,
  DescriptionTerm,
} from "@/components/ui/description-list";
```

```tsx
<DescriptionList>
  <DescriptionGroup>
    <DescriptionTerm>Status</DescriptionTerm>
    <DescriptionDetail>
      <span className="focus:ring-ring inline-flex items-center rounded-full border bg-green-50 px-2.5 py-0.5 text-xs font-semibold text-green-700 ring-green-600/20 transition-colors focus:ring-2 focus:ring-offset-2 focus:outline-none">
        Published
      </span>
    </DescriptionDetail>
  </DescriptionGroup>
  <DescriptionGroup>
    <DescriptionTerm>Last Updated</DescriptionTerm>
    <DescriptionDetail>Yesterday at 12:34 PM</DescriptionDetail>
  </DescriptionGroup>
  <DescriptionGroup>
    <DescriptionTerm>Storage Usage</DescriptionTerm>
    <DescriptionDetail>2.4 GB of 5 GB</DescriptionDetail>
  </DescriptionGroup>
  <DescriptionGroup>
    <DescriptionTerm>API Endpoints</DescriptionTerm>
    <DescriptionDetail>4 active endpoints</DescriptionDetail>
  </DescriptionGroup>
  <DescriptionGroup>
    <DescriptionTerm>Database</DescriptionTerm>
    <DescriptionDetail>PostgreSQL v14.5</DescriptionDetail>
  </DescriptionGroup>
  <DescriptionGroup>
    <DescriptionTerm>Environment</DescriptionTerm>
    <DescriptionDetail>Production</DescriptionDetail>
  </DescriptionGroup>
</DescriptionList>
```

## API Reference [#api-reference]

All parts render semantic HTML description-list elements and accept the corresponding element props.

### DescriptionList [#descriptionlist]

The list container. Renders a `<dl>`.

| Prop       | Type                         | Default | Description                         |
| ---------- | ---------------------------- | ------- | ----------------------------------- |
| `...props` | `React.ComponentProps<"dl">` | -       | Props spread to the `<dl>` element. |

### DescriptionGroup [#descriptiongroup]

Groups a term with its details for layout. Renders a `<div>`.

| Prop       | Type                          | Default | Description                          |
| ---------- | ----------------------------- | ------- | ------------------------------------ |
| `...props` | `React.ComponentProps<"div">` | -       | Props spread to the `<div>` element. |

### DescriptionTerm [#descriptionterm]

The term being described. Renders a `<dt>`.

| Prop       | Type                         | Default | Description                         |
| ---------- | ---------------------------- | ------- | ----------------------------------- |
| `...props` | `React.ComponentProps<"dt">` | -       | Props spread to the `<dt>` element. |

### DescriptionDetail [#descriptiondetail]

The description of the preceding term. Renders a `<dd>`.

| Prop       | Type                         | Default | Description                         |
| ---------- | ---------------------------- | ------- | ----------------------------------- |
| `...props` | `React.ComponentProps<"dd">` | -       | Props spread to the `<dd>` element. |

# Dropzone (/docs/components/dropzone)

<ComponentPreview name="dropzone-demo" />

## About [#about]

The `<Dropzone />` component is built on top of [react-dropzone](https://react-dropzone.js.org).

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/dropzone
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui/react
      ```

      <Step>
        Add the `<Empty />` component to your project.
      </Step>

      The `<Dropzone />` component uses the `<Empty />` component for its visual content. Make sure you have it installed in your project.

      See installation instructions for the [Empty](https://ui.shadcn.com/docs/components/empty) component.

      <Step>
        Add the `<DropzonePrimitive />` component to your project.
      </Step>

      The `<Dropzone />` component uses `<DropzonePrimitive />` component. Make sure you have it installed in your project.

      See installation instructions for the [DropzonePrimitive](/docs/primitives/dropzone#installation) component.

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="dropzone" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import {
  Empty,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@/components/ui/empty";
import {
  Dropzone,
  DropzoneInput,
  DropzoneUploadIcon,
  DropzoneZone,
} from "@/components/ui/dropzone";
```

```tsx
<Dropzone
  accept={{
    "image/*": [".jpg", ".png"],
    "application/pdf": [".pdf"],
  }}
  onDropAccepted={setFiles}
>
  <DropzoneZone>
    <DropzoneInput />
    <Empty>
      <EmptyHeader>
        <EmptyMedia variant="icon">
          <DropzoneUploadIcon />
        </EmptyMedia>
        <EmptyTitle>Drop files here or click to upload</EmptyTitle>
        <EmptyDescription>
          You can upload files up to 10MB in size. Supported formats: JPG, PNG,
          PDF.
        </EmptyDescription>
      </EmptyHeader>
    </Empty>
  </DropzoneZone>
</Dropzone>
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="dropzone-demo" />

### Trigger [#trigger]

<ComponentPreview name="dropzone-trigger" />

### Form [#form]

<ComponentPreview name="dropzone-form" />

## Accessibility [#accessibility]

The zone is focusable and opens the file dialog with <Kbd>Enter</Kbd> or <Kbd>Space</Kbd>, so the drag-and-drop interaction always has a keyboard equivalent. Make sure the zone contains visible text describing what to upload (such as `<EmptyTitle />` and `<EmptyDescription />`) — the upload icon alone is not an accessible name. Drag states are conveyed with color and iconography via the `<DropzoneUploadIcon />` swap; keep the title text meaningful so the state change is not communicated by color alone.

## API Reference [#api-reference]

Styled wrappers around the [Dropzone primitive](/docs/primitives/dropzone#api-reference) — see the primitive page for the full prop tables. The zone's title and description are composed with shadcn/ui's [Empty](https://ui.shadcn.com/docs/components/empty) component rather than a Dropzone-specific part.

### Dropzone [#dropzone]

Wraps [Root](/docs/primitives/dropzone#root) and accepts all [react-dropzone options](https://react-dropzone.js.org/#src) (`accept`, `maxFiles`, `onDropAccepted`, …).

### DropzoneZone [#dropzonezone]

Wraps [Zone](/docs/primitives/dropzone#zone) with dashed-border styling that reacts to the drag state data attributes.

### DropzoneInput [#dropzoneinput]

Wraps [Input](/docs/primitives/dropzone#input), the visually hidden file input.

### DropzoneUploadIcon [#dropzoneuploadicon]

Swaps the icon based on the drag state — an upload icon by default, a check when the drag is accepted and a ban icon when rejected. Render it inside `<EmptyMedia variant="icon" />`. Accepts the same props as a [Lucide](https://lucide.dev) icon.

### DropzoneTrigger [#dropzonetrigger]

Wraps [Trigger](/docs/primitives/dropzone#trigger) for opening the file dialog from a button outside the zone.

### DropzoneAccepted, DropzoneRejected [#dropzoneaccepted-dropzonerejected]

Wrap [Accepted and Rejected](/docs/primitives/dropzone#accepted), render-prop parts receiving the accepted files or rejections.

# Emoji Picker (/docs/components/emoji-picker)

<ComponentPreview name="emoji-picker-demo" />

## About [#about]

The `<EmojiPicker />` component is built on top of [frimousse](https://frimousse.liveblocks.io/).

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/emoji-picker
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui/react frimousse
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="emoji-picker" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import {
  EmojiPicker,
  EmojiPickerSearch,
  EmojiPickerContent,
  EmojiPickerFooter,
} from "@/components/ui/emoji-picker";
```

```tsx
<EmojiPicker>
  <EmojiPickerSearch />
  <EmojiPickerContent />
  <EmojiPickerFooter />
</EmojiPicker>
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="emoji-picker-demo" />

### Form [#form]

<ComponentPreview name="emoji-picker-form" />

<Callout className="mt-4">
  **Tip**: If you're looking to build a robust input field that supports emoji insertion, you're likely looking for a rich text editor. Some interesting solutions worth exploring include [Novel](https://novel.sh/) (powered by [Tiptap](https://tiptap.dev/)), [Plate](https://platejs.org/) (powered by [Slate](https://slatejs.org)), or [shadcn-editor](https://shadcn-editor.vercel.app/) (powered by [Lexical](https://lexical.dev/)). For lower-level control, you can also look into their underlying frameworks.
</Callout>

## API Reference [#api-reference]

Styled wrappers around [frimousse](https://frimousse.liveblocks.io/) — see the [frimousse API reference](https://frimousse.liveblocks.io/#api-reference) for the underlying props.

### EmojiPicker [#emojipicker]

Wraps `EmojiPicker.Root` and accepts all of its props (`onEmojiSelect`, `locale`, `skinTone`, `columns`, …).

### EmojiPickerSearch [#emojipickersearch]

Wraps `EmojiPicker.Search` with a search icon, accepting standard `<input>` props such as `placeholder`.

### EmojiPickerContent [#emojipickercontent]

Wraps `EmojiPicker.Viewport` with the loading, empty and list states already composed and styled.

### EmojiPickerFooter [#emojipickerfooter]

A footer showing a preview of the active emoji and a skin tone selector. Renders a `<div>` and accepts its props.

# Password Input (/docs/components/password-input)

<ComponentPreview name="password-input-demo" />

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/password-input
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Add `<InputGroup />` and `<PasswordInputPrimitive />` component to your project.
      </Step>

      The `<PasswordInput />` component uses `<InputGroup />` and `<PasswordInputPrimitive />` components. Make sure you have it installed in your project.

      See installation instructions for the [Input Group](https://ui.shadcn.com/docs/components/input-group) and [PasswordInputPrimitive](/docs/primitives/password-input#installation) components.

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="password-input" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import {
  PasswordInput,
  PasswordInputAdornmentToggle,
  PasswordInputInput,
} from "@/components/ui/password-input";
```

```tsx
<PasswordInput>
  <PasswordInputInput placeholder="Password" />
  <PasswordInputAdornmentToggle />
</PasswordInput>
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="password-input-demo" />

### Checkbox [#checkbox]

<ComponentPreview name="password-input-checkbox" />

### Form [#form]

<ComponentPreview name="password-input-form" />

## Accessibility [#accessibility]

The visibility toggle is icon-only — give it an accessible name, e.g. `<PasswordInputAdornmentToggle aria-label="Show password" />`. The eye icons are decorative and hidden from assistive technology. The input renders as `type="password"` until toggled, so browser and password-manager behavior is unaffected by the extra parts.

## API Reference [#api-reference]

Styled wrappers around the [Password Input primitive](/docs/primitives/password-input#api-reference) — see the primitive page for the full prop tables. Custom adornments, such as a leading lock icon, are composed with shadcn/ui's [Input Group](https://ui.shadcn.com/docs/components/input-group) parts (`InputGroupAddon`, `InputGroupButton`) rather than Password Input-specific parts.

### PasswordInput [#passwordinput]

Wraps [Root](/docs/primitives/password-input#root) (`visible`, `defaultVisible`, `onVisibleChange`), rendered as an [Input Group](https://ui.shadcn.com/docs/components/input-group); remaining props go to the group element.

### PasswordInputInput [#passwordinputinput]

Wraps [Input](/docs/primitives/password-input#input) with input-group styling. Accepts standard `<input>` props such as `placeholder` and `autoComplete`.

### PasswordInputAdornmentToggle [#passwordinputadornmenttoggle]

Wraps [Toggle](/docs/primitives/password-input#toggle) as an icon button in the trailing addon, swapping the eye icon based on the visibility state.

# Phone Input (/docs/components/phone-input)

<ComponentPreview name="phone-input-demo" />

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/phone-input
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install react-phone-number-input
      ```

      <Step>
        Add the `<PhoneInputPrimitive />`, `<Input />` and `<Select />` component to your project.
      </Step>

      The `<PhoneInput />` component uses `<PhoneInputPrimitive />`, `<Input />` and `<Select />` components. Make sure you have it installed in your project.

      See installation instructions for the [PhoneInputPrimitive](/docs/primitives/phone-input#installation), [Input](https://ui.shadcn.com/docs/components/input) and [Select](https://ui.shadcn.com/docs/components/select) components.

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="phone-input" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import { SelectTrigger } from "@/components/ui/select";
import { PhoneInput } from "@/components/ui/phone-input";
```

```tsx
<PhoneInput>
  <PhoneInputCountrySelect>
    <SelectTrigger>
      <PhoneInputCountrySelectValue />
    </SelectTrigger>
    <PhoneInputCountrySelectContent>
      <PhoneInputCountrySelectOptions />
    </PhoneInputCountrySelectContent>
  </PhoneInputCountrySelect>
  <PhoneInputInput />
</PhoneInput>
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="phone-input-demo" />

### Separated [#separated]

<ComponentPreview name="phone-input-separated" />

### Combobox [#combobox]

<ComponentPreview name="phone-input-combobox" />

### Form [#form]

<ComponentPreview name="phone-input-form" />

## Accessibility [#accessibility]

The country select trigger shows only a flag — give it an accessible name, e.g. `<SelectTrigger aria-label="Country" />`, and label the phone input itself like any text input (via `<Field>` / `<FieldLabel>` in forms or `aria-label`). Flags are decorative; each option in the dropdown carries the country's name as text, so the selection is not communicated by the flag alone.

## API Reference [#api-reference]

Styled wrappers around the [Phone Input primitive](/docs/primitives/phone-input#api-reference) — see the primitive page for the full prop tables.

### PhoneInput [#phoneinput]

Wraps [Root](/docs/primitives/phone-input#root) and accepts all of its props (`value`, `onValueChange`, `country`, `onCountryChange`, `preferredCountry`, `international`, …).

### PhoneInputInput [#phoneinputinput]

Wraps [Input](/docs/primitives/phone-input#input), rendered as the styled [Input](https://ui.shadcn.com/docs/components/input) with a stable `render` reference already applied.

### PhoneInputCountrySelect [#phoneinputcountryselect]

The country selector, built on the styled [Select](https://ui.shadcn.com/docs/components/select) and wired to the country state — `value` and `onValueChange` are managed for you. Compose it with Select's own `SelectTrigger` plus `PhoneInputCountrySelectValue` and `PhoneInputCountrySelectContent`, which layer country-aware behavior over the corresponding Select parts.

### PhoneInputCountrySelectOptions [#phoneinputcountryselectoptions]

Renders the full options list: the "International" item followed by every supported country with its flag, name and calling code.

### PhoneInputCountrySelectItem, PhoneInputCountrySelectInternationalItem [#phoneinputcountryselectitem-phoneinputcountryselectinternationalitem]

Individual option items for composing a custom list. `PhoneInputCountrySelectItem` requires a `value: Country`; the international item selects `null`.

### PhoneInputFlag [#phoneinputflag]

Renders the flag for a `country`, falling back to a globe icon for `null` (International).

# Time Field (/docs/components/time-field)

<ComponentPreview name="time-field-demo" />

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/time-field
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Add `<DateTimeField />` component to your project.
      </Step>

      The `<TimeField />` component uses the `<DateTimeField />` component. Make sure you have it installed in your project.

      See installation instructions for the [DateTimeField](/docs/components/date-time-field#installation) component.

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="time-field" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import {
  TimeField,
  TimeFieldAmPm,
  TimeFieldHours,
  TimeFieldMinutes,
  TimeFieldSeconds,
  TimeFieldSeparator,
} from "@/components/ui/time-field";
```

```tsx
<TimeField>
  <TimeFieldHours />
  <TimeFieldSeparator />
  <TimeFieldMinutes />
  <TimeFieldSeparator />
  <TimeFieldSeconds />
  <TimeFieldAmPm />
</TimeField>
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="time-field-demo" />

### With AM/PM [#with-ampm]

<ComponentPreview name="time-field-hour-12" />

### Form [#form]

<ComponentPreview name="time-field-form" />

## Accessibility [#accessibility]

The field follows the segment keyboard model and labeling guidance described in the [Date Time Field accessibility](/docs/components/date-time-field#accessibility) section, including <Kbd>A</Kbd> / <Kbd>P</Kbd> for the meridiem segment.

## API Reference [#api-reference]

A time-only preset of the [Date Time Field](/docs/components/date-time-field#api-reference) — each part wraps its Date Time Field counterpart and accepts the same props.

### TimeField [#timefield]

Wraps `DateTimeField` and accepts all of the [Root props](/docs/primitives/date-time-field#root) (`value`, `onValueChange`, `hour12`, …).

### TimeFieldHours, TimeFieldMinutes, TimeFieldSeconds [#timefieldhours-timefieldminutes-timefieldseconds]

Wrap the corresponding [segments](/docs/primitives/date-time-field#segments) with `--` as the default placeholder.

### TimeFieldAmPm [#timefieldampm]

Wraps [AmPm](/docs/primitives/date-time-field#ampm); renders only when the field has `hour12`.

### TimeFieldSeparator [#timefieldseparator]

Wraps the [separator](/docs/components/date-time-field#datetimefieldseparator) with `:` as the default children.

# Time (/docs/components/time)

<ComponentPreview name="time-demo" />

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/time
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install date-fns
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="time" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import { Time } from "@/components/ui/time";
```

```tsx
<Time />
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="time-demo" />

### Format [#format]

<ComponentPreview name="time-format" />

## API Reference [#api-reference]

### Time [#time]

Renders a semantic `<time>` element with a machine-readable `dateTime` attribute, formatting both with [date-fns format](https://date-fns.org/docs/format).

| Prop                | Type                           | Default        | Description                                       |
| ------------------- | ------------------------------ | -------------- | ------------------------------------------------- |
| `children`          | `Date \| string \| number`     | -              | The date to display. Required.                    |
| `formatStr`         | `string`                       | `"PPP"`        | The date-fns format for the visible text.         |
| `dateTimeFormatStr` | `string`                       | `"yyyy-MM-dd"` | The date-fns format for the `dateTime` attribute. |
| `...props`          | `React.ComponentProps<"time">` | -              | Props spread to the `<time>` element.             |

# Timeline (/docs/components/timeline)

<ComponentPreview name="timeline-demo" />

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/timeline
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="timeline" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDescription,
  TimelineDot,
  TimelineItem,
  TimelineSeparator,
  TimelineTitle,
} from "@/components/ui/timeline";
```

```tsx
<Timeline>
  <TimelineItem>
    <TimelineSeparator>
      <TimelineDot />
      <TimelineConnector />
    </TimelineSeparator>
    <TimelineContent>
      <TimelineTitle>Eat</TimelineTitle>
      <TimelineDescription>Because you need strength</TimelineDescription>
    </TimelineContent>
  </TimelineItem>
  <TimelineItem>
    <TimelineSeparator>
      <TimelineDot />
      <TimelineConnector />
    </TimelineSeparator>
    <TimelineContent>
      <TimelineTitle>Code</TimelineTitle>
      <TimelineDescription>Because it's awesome!</TimelineDescription>
    </TimelineContent>
  </TimelineItem>
  <TimelineItem>
    <TimelineSeparator>
      <TimelineDot />
      <TimelineConnector />
    </TimelineSeparator>
    <TimelineContent>
      <TimelineTitle>Sleep</TimelineTitle>
      <TimelineDescription>Because you need rest</TimelineDescription>
    </TimelineContent>
  </TimelineItem>
  <TimelineItem>
    <TimelineSeparator>
      <TimelineDot />
    </TimelineSeparator>
    <TimelineContent>
      <TimelineTitle>Repeat</TimelineTitle>
      <TimelineDescription>
        Because this is the life you love!
      </TimelineDescription>
    </TimelineContent>
  </TimelineItem>
</Timeline>
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="timeline-demo" />

### Alternate [#alternate]

<ComponentPreview name="timeline-alternate" />

### With Icon [#with-icon]

<ComponentPreview name="timeline-with-icon" />

### Horizontal [#horizontal]

<ComponentPreview name="timeline-horizontal" />

## Accessibility [#accessibility]

The timeline renders an ordered list (`<ol role="list">`), so assistive technology announces the number of events and their order. Dots and connectors are purely visual — keep the meaning of each event in its `TimelineTitle` and `TimelineDescription` text rather than in the dot's color or icon alone.

## API Reference [#api-reference]

### Timeline [#timeline]

The list container. Renders an `<ol>`.

| Prop          | Type                         | Default      | Description                           |
| ------------- | ---------------------------- | ------------ | ------------------------------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | The layout direction of the timeline. |
| `...props`    | `React.ComponentProps<"ol">` | -            | Props spread to the list element.     |

### TimelineItem [#timelineitem]

A single event. Renders an `<li>`.

| Prop       | Type                         | Default | Description                       |
| ---------- | ---------------------------- | ------- | --------------------------------- |
| `render`   | `ReactElement \| function`   | -       | Render as a different element.    |
| `...props` | `React.ComponentProps<"li">` | -       | Props spread to the item element. |

### TimelineSeparator [#timelineseparator]

Lays out the dot and connector alongside the content. Renders a `<div>`.

| Prop       | Type                          | Default | Description                            |
| ---------- | ----------------------------- | ------- | -------------------------------------- |
| `render`   | `ReactElement \| function`    | -       | Render as a different element.         |
| `...props` | `React.ComponentProps<"div">` | -       | Props spread to the separator element. |

### TimelineDot [#timelinedot]

The event marker. Renders a `<div>` showing a dot while empty; place an icon inside to replace it.

| Prop       | Type                          | Default     | Description                                 |
| ---------- | ----------------------------- | ----------- | ------------------------------------------- |
| `variant`  | `"default" \| "outline"`      | `"default"` | Filled or outlined dot when rendered empty. |
| `render`   | `ReactElement \| function`    | -           | Render as a different element.              |
| `...props` | `React.ComponentProps<"div">` | -           | Props spread to the dot element.            |

### TimelineConnector [#timelineconnector]

The line connecting one event to the next. Renders a `<div>`; omit it on the last item.

| Prop       | Type                          | Default | Description                            |
| ---------- | ----------------------------- | ------- | -------------------------------------- |
| `render`   | `ReactElement \| function`    | -       | Render as a different element.         |
| `...props` | `React.ComponentProps<"div">` | -       | Props spread to the connector element. |

### TimelineContent, TimelineTitle, TimelineDescription [#timelinecontent-timelinetitle-timelinedescription]

The event's content, heading text and supporting text. Each renders a `<div>` and supports the `render` prop.

### useTimeline [#usetimeline]

Hook exposing the timeline context (`orientation`) for building custom parts. Must be used within `<Timeline />`.

# Wheel Picker (/docs/components/wheel-picker)

<ComponentPreview name="wheel-picker-demo" />

## About [#about]

The `<WheelPicker />` component is built on top of [react-wheel-picker](https://react-wheel-picker.chanhdai.com/).

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/wheel-picker
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="wheel-picker" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import { WheelPicker, WheelPickerWrapper } from "@/components/ui/wheel-picker";
```

```tsx
<WheelPickerWrapper>
  <WheelPicker />
</WheelPickerWrapper>
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="wheel-picker-demo" />

### Form [#form]

<ComponentPreview name="wheel-picker-form" />

## Accessibility [#accessibility]

Each `<WheelPicker />` column is keyboard-operable: focus it and use <Kbd>Up</Kbd>/<Kbd>Down</Kbd> (or <Kbd>Left</Kbd>/<Kbd>Right</Kbd> when laid out horizontally) to move one option at a time, matching the pointer/touch scroll behavior. See react-wheel-picker's [accessibility notes](https://react-wheel-picker.chanhdai.com/docs#api-reference) for the full set of keyboard and ARIA behavior it provides.

Give each `<WheelPicker />` an accessible name (e.g. wrap it with a `<label>` or pass `aria-label`) when a column's purpose isn't obvious from surrounding text, such as separate hour/minute columns in a time picker.

## API Reference [#api-reference]

Styled wrappers around [react-wheel-picker](https://react-wheel-picker.chanhdai.com/) — see its [API reference](https://react-wheel-picker.chanhdai.com/docs#api-reference) for the underlying props.

### WheelPickerWrapper [#wheelpickerwrapper]

Wraps `WheelPickerWrapper` with border and highlight styling. Place one or more `<WheelPicker />` columns inside.

### WheelPicker [#wheelpicker]

Wraps `WheelPicker` with themed option and highlight classes, and accepts all of its props (`options`, `value`, `onValueChange`, `infinite`, `visibleCount`, …). The exported `WheelPickerOption` type describes the `options` items.

# Date Picker (/docs/primitives/date-picker)

<ComponentPreview name="date-picker-primitive-demo" />

<Callout className="mt-4 bg-amber-50 border-amber-200 dark:bg-amber-950/50 dark:border-amber-950 [&_[data-slot=alert-description]]:text-foreground">
  **Unstyled**: This is an unstyled primitive. For a ready-to-use, shadcn-styled version, see the [Date Picker](/docs/components/date-picker) component.
</Callout>

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/date-picker-primitive
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui/react @base-ui/utils date-fns react-day-picker
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="date-picker-primitive" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Anatomy [#anatomy]

Import all parts and piece them together.

```tsx
import * as DatePickerPrimitive from "@/components/ui/date-picker-primitive";

export default () => (
  <DatePickerPrimitive.Root>
    <DatePickerPrimitive.Trigger>
      <DatePickerPrimitive.Value />
    </DatePickerPrimitive.Trigger>
    <DatePickerPrimitive.DateField>
      <DatePickerPrimitive.DateFieldDays />
      <DatePickerPrimitive.DateFieldSeparator />
      <DatePickerPrimitive.DateFieldMonths />
      <DatePickerPrimitive.DateFieldSeparator />
      <DatePickerPrimitive.DateFieldYears />
    </DatePickerPrimitive.DateField>
    <DatePickerPrimitive.Clear />
    <DatePickerPrimitive.Anchor />

    <DatePickerPrimitive.Portal>
      <DatePickerPrimitive.Positioner>
        <DatePickerPrimitive.Content>
          <DatePickerPrimitive.Calendar />
        </DatePickerPrimitive.Content>
      </DatePickerPrimitive.Positioner>
    </DatePickerPrimitive.Portal>
  </DatePickerPrimitive.Root>
);
```

## Examples [#examples]

### Input [#input]

<ComponentPreview name="date-picker-primitive-input" />

### Multiple [#multiple]

<ComponentPreview name="date-picker-primitive-multiple" />

### Range [#range]

<ComponentPreview name="date-picker-primitive-range" />

## API Reference [#api-reference]

### Root [#root]

Manages the selected value, the visible month and the popover state. Built on top of [Base UI Popover](https://base-ui.com/react/components/popover).

| Prop            | Type                                  | Default       | Description                                                                                                       |
| --------------- | ------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------- |
| `mode`          | `"single" \| "multiple" \| "range"`   | `"single"`    | The selection mode. Determines the value type below.                                                              |
| `required`      | `boolean`                             | `false`       | Prevents clearing the selection. When set, the value is no longer nullable.                                       |
| `value`         | `Date \| Date[] \| DateRange \| null` | -             | The selected value, typed by `mode`. Use for controlled value; pass `null` for empty.                             |
| `defaultValue`  | `Date \| Date[] \| DateRange`         | -             | The initial value when uncontrolled.                                                                              |
| `onValueChange` | `(value) => void`                     | -             | Called when the selection changes. The value is typed by `mode`.                                                  |
| `formatStr`     | `string`                              | `"PPP"`       | The [date-fns format](https://date-fns.org/docs/format) used by `Value` to display the selection.                 |
| `month`         | `Date`                                | -             | The month shown in the calendar. Use for controlled month.                                                        |
| `defaultMonth`  | `Date`                                | current month | The initial month when uncontrolled.                                                                              |
| `onMonthChange` | `(month: Date) => void`               | -             | Called when the visible month changes.                                                                            |
| `disabled`      | `boolean`                             | -             | Disables the trigger, the clear button and the calendar.                                                          |
| `...props`      | `PopoverPrimitive.Root.Props`         | -             | Remaining props are spread to [Base UI Popover.Root](https://base-ui.com/react/components/popover#api-reference). |

### Trigger [#trigger]

Opens the popover. See the [Base UI Popover.Trigger](https://base-ui.com/react/components/popover#api-reference) documentation for more information.

### Value [#value]

Displays the current selection formatted with `formatStr`, joining multiple dates with `", "` and ranges as `from - to`. Has a `data-placeholder` attribute while empty. Renders a `<span>` by default.

| Prop          | Type                           | Default | Description                        |
| ------------- | ------------------------------ | ------- | ---------------------------------- |
| `placeholder` | `ReactNode`                    | -       | Content shown while empty.         |
| `render`      | `ReactElement \| function`     | -       | Render as a different element.     |
| `...props`    | `React.ComponentProps<"span">` | -       | Props spread to the value element. |

### Clear [#clear]

Clears the selection. Disabled while the value is empty or the root is `required`. Renders a `<button type="button">` by default.

| Prop       | Type                             | Default | Description                        |
| ---------- | -------------------------------- | ------- | ---------------------------------- |
| `render`   | `ReactElement \| function`       | -       | Render as a different element.     |
| `...props` | `React.ComponentProps<"button">` | -       | Props spread to the clear element. |

### DateField [#datefield]

An inline [Date Time Field](/docs/primitives/date-time-field) synced with the picker — typing a date updates the selection and the visible month. Only usable when `mode` is `"single"`. Accepts the [Date Time Field Root props](/docs/primitives/date-time-field#root) except `value` and `onValueChange`, which are managed by the picker. Compose it with the `DateFieldDays`, `DateFieldMonths`, `DateFieldYears` and `DateFieldSeparator` [segments](/docs/primitives/date-time-field#segments).

### DateRangeField [#daterangefield]

An inline [Date Time Range Field](/docs/primitives/date-time-range-field) synced with the picker. Only usable when `mode` is `"range"`. Accepts the [Date Time Range Field Root props](/docs/primitives/date-time-range-field#root) except `value` and `onValueChange`. Compose it with `DateRangeFieldFrom` and `DateRangeFieldTo` containers wrapping the `DateRangeFieldDays`, `DateRangeFieldMonths`, `DateRangeFieldYears` and `DateRangeFieldSeparator` [segments](/docs/primitives/date-time-range-field#segments).

### Anchor [#anchor]

An optional element the popover positions against instead of the trigger. Renders a `<div>` by default.

| Prop       | Type                          | Default | Description                         |
| ---------- | ----------------------------- | ------- | ----------------------------------- |
| `render`   | `ReactElement \| function`    | -       | Render as a different element.      |
| `...props` | `React.ComponentProps<"div">` | -       | Props spread to the anchor element. |

### Portal, Positioner, Content [#portal-positioner-content]

Thin wrappers around the corresponding [Base UI Popover](https://base-ui.com/react/components/popover#api-reference) parts (`Portal`, `Positioner` and `Popup`). `Positioner` anchors to the `Anchor` element when one is rendered. See the Base UI documentation for more information.

### Calendar [#calendar]

The calendar inside the popover, rendered with [react-day-picker](https://daypicker.dev). Selection, month and disabled state are wired to the root.

| Prop        | Type             | Default | Description                                                                                                                                                     |
| ----------- | ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autoFocus` | `boolean`        | `true`  | Focuses the calendar when the popover opens.                                                                                                                    |
| `render`    | `ReactElement`   | -       | Render a custom `DayPicker` element, e.g. a styled calendar component.                                                                                          |
| `...props`  | `DayPickerProps` | -       | Remaining [react-day-picker props](https://daypicker.dev/api/type-aliases/DayPickerProps) are spread, except the selection and month props managed by the root. |

### useDatePicker [#usedatepicker]

Hook exposing the date picker context (`mode`, `value`, `onValueChange`, `month`, `onMonthChange`, `formatStr`, `required`, `disabled`, `anchor`, `onAnchorChange`) for building custom parts. Must be used within `<DatePickerPrimitive.Root>`.

# Date Time Field (/docs/primitives/date-time-field)

<ComponentPreview name="date-time-field-primitive-demo" />

## About [#about]

The `<DateTimeFieldPrimitive />` component is built on top of [timescape](https://timescape.daniellehr.de), wrapping the library to deliver a more consistent API that aligns with Base UI conventions.

<Callout className="mt-4 bg-amber-50 border-amber-200 dark:bg-amber-950/50 dark:border-amber-950 [&_[data-slot=alert-description]]:text-foreground">
  **Unstyled**: This is an unstyled primitive. For a ready-to-use, shadcn-styled version, see the [Date Time Field](/docs/components/date-time-field) component.
</Callout>

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/date-time-field-primitive
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui/react timescape
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      `date-time-field-primitive.tsx`

      <ComponentSource name="date-time-field-primitive" />

      `use-timescape.ts`

      <ComponentSource name="date-time-field-primitive" fileName="use-timescape" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Anatomy [#anatomy]

Import all parts and piece them together.

```tsx
import * as DateTimeFieldPrimitive from "@/components/ui/date-time-field-primitive";

export default () => (
  <DateTimeFieldPrimitive.Root>
    <DateTimeFieldPrimitive.Days />
    <DateTimeFieldPrimitive.Separator />
    <DateTimeFieldPrimitive.Months />
    <DateTimeFieldPrimitive.Separator />
    <DateTimeFieldPrimitive.Years />
    <DateTimeFieldPrimitive.Separator />
    <DateTimeFieldPrimitive.Hours />
    <DateTimeFieldPrimitive.Separator />
    <DateTimeFieldPrimitive.Minutes />
    <DateTimeFieldPrimitive.Separator />
    <DateTimeFieldPrimitive.Seconds />
    <DateTimeFieldPrimitive.Separator />
    <DateTimeFieldPrimitive.AmPm />
  </DateTimeFieldPrimitive.Root>
);
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="date-time-field-primitive-demo" />

### Disabled [#disabled]

<ComponentPreview name="date-time-field-primitive-disabled" />

## API Reference [#api-reference]

### Root [#root]

Runs [timescape](https://github.com/dan-lee/timescape) and provides its state to the segments. Renders a `<div>` by default that manages focus between segments.

| Prop            | Type                            | Default     | Description                                                                |
| --------------- | ------------------------------- | ----------- | -------------------------------------------------------------------------- |
| `value`         | `Date \| null`                  | -           | The date value. Use for controlled value; pass `null` for empty.           |
| `defaultValue`  | `Date`                          | -           | The initial value when uncontrolled.                                       |
| `onValueChange` | `(value: Date \| null) => void` | -           | Called when the value changes.                                             |
| `digits`        | `"numeric" \| "2-digit"`        | `"2-digit"` | Whether segments are zero-padded.                                          |
| `hour12`        | `boolean`                       | `false`     | Use a 12-hour clock. Required for the `AmPm` segment to render.            |
| `minDate`       | `Date`                          | -           | The minimum selectable date.                                               |
| `maxDate`       | `Date`                          | -           | The maximum selectable date.                                               |
| `snapToStep`    | `boolean`                       | `false`     | Snap values to the segment's `step` when incrementing.                     |
| `wheelControl`  | `boolean`                       | `false`     | Allow changing segment values with the mouse wheel.                        |
| `wrapAround`    | `boolean`                       | `false`     | Wrap from the last value back to the first when incrementing past the end. |
| `disabled`      | `boolean`                       | -           | Disables every segment.                                                    |
| `render`        | `ReactElement \| function`      | -           | Render as a different element.                                             |
| `...props`      | `React.ComponentProps<"div">`   | -           | Props spread to the root element.                                          |

See the [timescape options](https://github.com/dan-lee/timescape?tab=readme-ov-file#options) for more detail on the option props.

### Segments [#segments]

The `Days`, `Months`, `Years`, `Hours`, `Minutes` and `Seconds` parts. Each renders an `<input>` wired to its timescape segment and shares the same props.

| Prop       | Type                            | Default | Description                          |
| ---------- | ------------------------------- | ------- | ------------------------------------ |
| `disabled` | `boolean`                       | -       | Disables this segment only.          |
| `render`   | `ReactElement \| function`      | -       | Render as a different element.       |
| `...props` | `React.ComponentProps<"input">` | -       | Props spread to the segment element. |

### AmPm [#ampm]

The meridiem segment. Renders only when the root has `hour12`; toggle it with <Kbd>A</Kbd> / <Kbd>P</Kbd> or the arrow keys. Same props as the other segments.

### Separator [#separator]

A decorative separator between segments (e.g. `/` or `:`). Hidden from assistive technology with `aria-hidden`. Renders a `<span>` by default.

| Prop       | Type                           | Default | Description                            |
| ---------- | ------------------------------ | ------- | -------------------------------------- |
| `render`   | `ReactElement \| function`     | -       | Render as a different element.         |
| `...props` | `React.ComponentProps<"span">` | -       | Props spread to the separator element. |

### useDateTimeField [#usedatetimefield]

Hook exposing the field context (`getInputProps`, `getRootProps`, `options`, `disabled`) for building custom segments. Must be used within `<DateTimeFieldPrimitive.Root>`.

# Date Time Range Field (/docs/primitives/date-time-range-field)

<ComponentPreview name="date-time-range-field-primitive-demo" />

## About [#about]

The `<DateTimeRangeFieldPrimitive />` component is built on top of [timescape](https://timescape.daniellehr.de), wrapping the library to deliver a more consistent API that aligns with Base UI conventions.

<Callout className="mt-4 bg-amber-50 border-amber-200 dark:bg-amber-950/50 dark:border-amber-950 [&_[data-slot=alert-description]]:text-foreground">
  **Unstyled**: This is an unstyled primitive. For a ready-to-use, shadcn-styled version, see the [Date Time Range Field](/docs/components/date-time-range-field) component.
</Callout>

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/date-time-range-field-primitive
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui/react timescape
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      `date-time-range-field-primitive.tsx`

      <ComponentSource name="date-time-range-field-primitive" />

      `use-timescape.ts`

      <ComponentSource name="date-time-range-field-primitive" fileName="use-timescape" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Anatomy [#anatomy]

Import all parts and piece them together.

```tsx
import * as DateTimeRangeFieldPrimitive from "@/components/ui/date-time-range-field-primitive";

export default () => (
  <DateTimeRangeFieldPrimitive.Root>
    <DateTimeRangeFieldPrimitive.From>
      <DateTimeRangeFieldPrimitive.Days />
      <DateTimeRangeFieldPrimitive.Separator />
      <DateTimeRangeFieldPrimitive.Months />
      <DateTimeRangeFieldPrimitive.Separator />
      <DateTimeRangeFieldPrimitive.Years />
      <DateTimeRangeFieldPrimitive.Separator />
      <DateTimeRangeFieldPrimitive.Hours />
      <DateTimeRangeFieldPrimitive.Separator />
      <DateTimeRangeFieldPrimitive.Minutes />
      <DateTimeRangeFieldPrimitive.Separator />
      <DateTimeRangeFieldPrimitive.Seconds />
      <DateTimeRangeFieldPrimitive.Separator />
      <DateTimeRangeFieldPrimitive.AmPm />
    </DateTimeRangeFieldPrimitive.From>

    <DateTimeRangeFieldPrimitive.Separator />

    <DateTimeRangeFieldPrimitive.To>
      <DateTimeRangeFieldPrimitive.Days />
      <DateTimeRangeFieldPrimitive.Separator />
      <DateTimeRangeFieldPrimitive.Months />
      <DateTimeRangeFieldPrimitive.Separator />
      <DateTimeRangeFieldPrimitive.Years />
      <DateTimeRangeFieldPrimitive.Separator />
      <DateTimeRangeFieldPrimitive.Hours />
      <DateTimeRangeFieldPrimitive.Separator />
      <DateTimeRangeFieldPrimitive.Minutes />
      <DateTimeRangeFieldPrimitive.Separator />
      <DateTimeRangeFieldPrimitive.Seconds />
      <DateTimeRangeFieldPrimitive.Separator />
      <DateTimeRangeFieldPrimitive.AmPm />
    </DateTimeRangeFieldPrimitive.To>
  </DateTimeRangeFieldPrimitive.Root>
);
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="date-time-range-field-primitive-demo" />

### Disabled [#disabled]

<ComponentPreview name="date-time-range-field-primitive-disabled" />

## API Reference [#api-reference]

### Root [#root]

Runs [timescape](https://github.com/dan-lee/timescape)'s range mode and provides the `from` and `to` fields to the parts below. Renders a `<div>` by default that manages focus across both fields.

| Prop            | Type                                 | Default     | Description                                                                                      |
| --------------- | ------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------ |
| `value`         | `DateRange \| null`                  | -           | The range value (`{ from?: Date; to?: Date }`). Use for controlled value; pass `null` for empty. |
| `defaultValue`  | `DateRange`                          | -           | The initial value when uncontrolled.                                                             |
| `onValueChange` | `(value: DateRange \| null) => void` | -           | Called when the range changes.                                                                   |
| `digits`        | `"numeric" \| "2-digit"`             | `"2-digit"` | Whether segments are zero-padded.                                                                |
| `hour12`        | `boolean`                            | `false`     | Use a 12-hour clock. Required for the `AmPm` segments to render.                                 |
| `minDate`       | `Date`                               | -           | The minimum selectable date.                                                                     |
| `maxDate`       | `Date`                               | -           | The maximum selectable date.                                                                     |
| `snapToStep`    | `boolean`                            | `false`     | Snap values to the segment's `step` when incrementing.                                           |
| `wheelControl`  | `boolean`                            | `false`     | Allow changing segment values with the mouse wheel.                                              |
| `wrapAround`    | `boolean`                            | `false`     | Wrap from the last value back to the first when incrementing past the end.                       |
| `from`          | `TimescapeOptions`                   | -           | Option overrides applied to the `from` field only.                                               |
| `to`            | `TimescapeOptions`                   | -           | Option overrides applied to the `to` field only.                                                 |
| `disabled`      | `boolean`                            | -           | Disables every segment.                                                                          |
| `render`        | `ReactElement \| function`           | -           | Render as a different element.                                                                   |
| `...props`      | `React.ComponentProps<"div">`        | -           | Props spread to the root element.                                                                |

See the [timescape options](https://github.com/dan-lee/timescape?tab=readme-ov-file#options) for more detail on the option props.

### From, To [#from-to]

Containers that scope the segments inside them to the start or end of the range. Segments must be placed inside one of the two. Each renders a `<div>` by default.

| Prop       | Type                          | Default | Description                            |
| ---------- | ----------------------------- | ------- | -------------------------------------- |
| `render`   | `ReactElement \| function`    | -       | Render as a different element.         |
| `...props` | `React.ComponentProps<"div">` | -       | Props spread to the container element. |

### Segments [#segments]

The `Days`, `Months`, `Years`, `Hours`, `Minutes` and `Seconds` parts, identical to the [Date Time Field segments](/docs/primitives/date-time-field#segments). Each renders an `<input>` and must live inside `From` or `To`.

| Prop       | Type                            | Default | Description                          |
| ---------- | ------------------------------- | ------- | ------------------------------------ |
| `disabled` | `boolean`                       | -       | Disables this segment only.          |
| `render`   | `ReactElement \| function`      | -       | Render as a different element.       |
| `...props` | `React.ComponentProps<"input">` | -       | Props spread to the segment element. |

### AmPm [#ampm]

The meridiem segment. Renders only when `hour12` is set for its field. Same props as the other segments.

### Separator [#separator]

A decorative separator, hidden from assistive technology with `aria-hidden`. Renders a `<span>` by default.

| Prop       | Type                           | Default | Description                            |
| ---------- | ------------------------------ | ------- | -------------------------------------- |
| `render`   | `ReactElement \| function`     | -       | Render as a different element.         |
| `...props` | `React.ComponentProps<"span">` | -       | Props spread to the separator element. |

### useDateTimeRangeField [#usedatetimerangefield]

Hook exposing the range field context (`from`, `to`, `getRootProps`, `disabled`) for building custom parts. Must be used within `<DateTimeRangeFieldPrimitive.Root>`.

# Dropzone (/docs/primitives/dropzone)

<ComponentPreview name="dropzone-primitive-demo" />

## About [#about]

The `<DropzonePrimitive />` component is built on top of [react-dropzone](https://react-dropzone.js.org), wrapping the library to deliver a more consistent API that aligns with Base UI conventions.

<Callout className="mt-4 bg-amber-50 border-amber-200 dark:bg-amber-950/50 dark:border-amber-950 [&_[data-slot=alert-description]]:text-foreground">
  **Unstyled**: This is an unstyled primitive. For a ready-to-use, shadcn-styled version, see the [Dropzone](/docs/components/dropzone) component.
</Callout>

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/dropzone-primitive
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui/react react-dropzone
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="dropzone-primitive" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Anatomy [#anatomy]

```tsx
import * as DropzonePrimitive from "@/components/ui/dropzone-primitive";

export default () => (
  <DropzonePrimitive.Root>
    <DropzonePrimitive.Input />
    <DropzonePrimitive.Zone />
    <DropzonePrimitive.Trigger />
    <DropzonePrimitive.DragAccepted />
    <DropzonePrimitive.DragRejected />
    <DropzonePrimitive.DragDefault />
    <DropzonePrimitive.Accepted />
    <DropzonePrimitive.Rejected />
  </DropzonePrimitive.Root>
);
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="dropzone-primitive-demo" />

## API Reference [#api-reference]

### Root [#root]

The dropzone provider. Runs [react-dropzone](https://react-dropzone.js.org)'s `useDropzone` and shares its state with the parts below. Renders no element of its own.

| Prop         | Type                                                      | Default | Description                                                                                                                                                                             |
| ------------ | --------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children`   | `ReactNode \| (state: DropzoneContextProps) => ReactNode` | -       | The dropzone parts, or a render function that receives the full dropzone state and options.                                                                                             |
| `...options` | `DropzoneOptions`                                         | -       | All [react-dropzone options](https://react-dropzone.js.org/#!/Dropzone) — `accept`, `maxFiles`, `maxSize`, `multiple`, `disabled`, `noClick`, `noKeyboard`, `onDrop`, `validator`, etc. |

### Input [#input]

The visually hidden file input. Merges react-dropzone's `getInputProps`. Renders an `<input type="file">` by default.

| Prop       | Type                            | Default | Description                                     |
| ---------- | ------------------------------- | ------- | ----------------------------------------------- |
| `render`   | `ReactElement \| function`      | -       | Render as a different element.                  |
| `...props` | `React.ComponentProps<"input">` | -       | Props merged into react-dropzone's input props. |

### Zone [#zone]

The droppable area. Merges react-dropzone's `getRootProps`, so by default it is focusable and opens the file dialog on click, <Kbd>Enter</Kbd> or <Kbd>Space</Kbd>. Renders a `<div>` by default.

| Prop       | Type                          | Default | Description                                    |
| ---------- | ----------------------------- | ------- | ---------------------------------------------- |
| `render`   | `ReactElement \| function`    | -       | Render as a different element.                 |
| `...props` | `React.ComponentProps<"div">` | -       | Props merged into react-dropzone's root props. |

The zone exposes its state for styling via data attributes: `data-drag-active`, `data-drag-accept`, `data-drag-reject`, `data-focused`, `data-file-dialog-active` and `data-disabled`, plus the option flags `data-no-click`, `data-no-keyboard`, `data-no-drag`, `data-no-drag-events-bubbling` and `data-prevent-drop-on-document`.

### Trigger [#trigger]

A button that opens the file dialog. Useful when the zone itself has `noClick`. Renders a `<button>` by default.

| Prop       | Type                             | Default | Description                          |
| ---------- | -------------------------------- | ------- | ------------------------------------ |
| `render`   | `ReactElement \| function`       | -       | Render as a different element.       |
| `...props` | `React.ComponentProps<"button">` | -       | Props spread to the trigger element. |

### DragAccepted [#dragaccepted]

Renders its children only while a drag over the zone would be accepted.

| Prop       | Type        | Default | Description                                 |
| ---------- | ----------- | ------- | ------------------------------------------- |
| `children` | `ReactNode` | -       | Content shown while the drag is acceptable. |

### DragRejected [#dragrejected]

Renders its children only while a drag over the zone would be rejected.

| Prop       | Type        | Default | Description                               |
| ---------- | ----------- | ------- | ----------------------------------------- |
| `children` | `ReactNode` | -       | Content shown while the drag is rejected. |

### DragDefault [#dragdefault]

Renders its children only while no drag is in progress.

| Prop       | Type        | Default | Description                            |
| ---------- | ----------- | ------- | -------------------------------------- |
| `children` | `ReactNode` | -       | Content shown when nothing is dragged. |

### Accepted [#accepted]

Render-prop container for the accepted files.

| Prop       | Type                                                    | Default | Description                                       |
| ---------- | ------------------------------------------------------- | ------- | ------------------------------------------------- |
| `children` | `(acceptedFiles: readonly FileWithPath[]) => ReactNode` | -       | Render function that receives the accepted files. |

### Rejected [#rejected]

Render-prop container for the rejected files.

| Prop       | Type                                                      | Default | Description                                        |
| ---------- | --------------------------------------------------------- | ------- | -------------------------------------------------- |
| `children` | `(fileRejections: readonly FileRejection[]) => ReactNode` | -       | Render function that receives the file rejections. |

# Password Input (/docs/primitives/password-input)

<ComponentPreview name="password-input-primitive-demo" />

<Callout className="mt-4 bg-amber-50 border-amber-200 dark:bg-amber-950/50 dark:border-amber-950 [&_[data-slot=alert-description]]:text-foreground">
  **Unstyled**: This is an unstyled primitive. For a ready-to-use, shadcn-styled version, see the [Password Input](/docs/components/password-input) component.
</Callout>

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/password-input-primitive
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui/react @base-ui/utils
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="password-input-primitive" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Anatomy [#anatomy]

```tsx
import * as PasswordInputPrimitive from "@/components/ui/password-input-primitive";

export default () => (
  <PasswordInputPrimitive.Root>
    <PasswordInputPrimitive.Input />
    <PasswordInputPrimitive.Toggle />
    <PasswordInputPrimitive.Indicator />
  </PasswordInputPrimitive.Root>
);
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="password-input-primitive-demo" />

### Checkbox [#checkbox]

<ComponentPreview name="password-input-primitive-checkbox" />

## API Reference [#api-reference]

### Root [#root]

Manages the visibility state and provides it to the parts below. Renders no element of its own.

| Prop              | Type                         | Default | Description                                                     |
| ----------------- | ---------------------------- | ------- | --------------------------------------------------------------- |
| `visible`         | `boolean`                    | -       | Whether the password is visible. Use for controlled visibility. |
| `defaultVisible`  | `boolean`                    | `false` | The initial visibility when uncontrolled.                       |
| `onVisibleChange` | `(visible: boolean) => void` | -       | Called when the visibility changes.                             |
| `children`        | `ReactNode`                  | -       | The password input parts.                                       |

### Input [#input]

The password input. Switches its `type` between `password` and `text` based on the visibility. Renders an `<input>` by default.

| Prop       | Type                            | Default | Description                        |
| ---------- | ------------------------------- | ------- | ---------------------------------- |
| `render`   | `ReactElement \| function`      | -       | Render as a different element.     |
| `...props` | `React.ComponentProps<"input">` | -       | Props spread to the input element. |

### Toggle [#toggle]

Toggles the visibility. Renders a `<button type="button">` by default; the render function receives the `{ visible }` state.

| Prop       | Type                             | Default | Description                                                      |
| ---------- | -------------------------------- | ------- | ---------------------------------------------------------------- |
| `render`   | `ReactElement \| function`       | -       | Render as a different element. Receives the `{ visible }` state. |
| `...props` | `React.ComponentProps<"button">` | -       | Props spread to the toggle element.                              |

### Indicator [#indicator]

A presentational slot for visibility-dependent content such as an eye icon. Hidden from assistive technology with `aria-hidden`. Renders a `<span>` by default; the render function receives the `{ visible }` state.

| Prop       | Type                           | Default | Description                                                      |
| ---------- | ------------------------------ | ------- | ---------------------------------------------------------------- |
| `render`   | `ReactElement \| function`     | -       | Render as a different element. Receives the `{ visible }` state. |
| `...props` | `React.ComponentProps<"span">` | -       | Props spread to the indicator element.                           |

# Phone Input (/docs/primitives/phone-input)

<ComponentPreview name="phone-input-primitive-demo" />

## About [#about]

The `<PhoneInput />` component is built on top of [react-phone-number-input](https://catamphetamine.gitlab.io/react-phone-number-input/), wrapping the library to deliver a more consistent API that aligns with Base UI conventions.

<Callout className="mt-4 bg-amber-50 border-amber-200 dark:bg-amber-950/50 dark:border-amber-950 [&_[data-slot=alert-description]]:text-foreground">
  **Unstyled**: This is an unstyled primitive. For a ready-to-use, shadcn-styled version, see the [Phone Input](/docs/components/phone-input) component.
</Callout>

<Callout className="mt-4 bg-amber-50 border-amber-200 dark:bg-amber-950/50 dark:border-amber-950 [&_[data-slot=alert-description]]:text-foreground">
  **Important**: This component implements a non-standard controlled behavior that differs from typical React patterns. The underlying library maintains its own internal state alongside any external state management, making it a "semi-controlled" component. While it works somewhat reliably, it may not behave as expected if you're used to idiomatic controlled components. See the [related issue](https://gitlab.com/catamphetamine/react-phone-number-input/-/issues/249) for technical details.
</Callout>

## Understanding Phone Formats [#understanding-phone-formats]

Phone numbers can be represented in different formats depending on the context. Understanding these formats is crucial for using the component effectively.

### National Format [#national-format]

National format represents phone numbers in their local, country-specific format. This format is most familiar to users within a specific country. For example:

* US: `(234) 567-8900`
* UK: `01234 567890`
* MY: `012-345 6789`
* JP: `0123-45-6789`

### International Format [#international-format]

International format follows the [E.164 standard](https://en.wikipedia.org/wiki/E.164), which provides a consistent way to represent phone numbers globally. This format can be displayed in two variants:

1. **Without Country Code**

   Shows only the subscriber number without the country calling code prefix, useful when the country is already known through the country select or other context. For example:

   * US: `234 567 8900`
   * UK: `1234 567890`
   * MY: `12 345 6789`
   * JP: `123 45 6789`

2. **With Country Code**

   Includes the country calling code prefix, a universal representation that works across all countries. For example:

   * US: `+1 234 567 8900`
   * UK: `+44 1234 567890`
   * MY: `+60 12 345 6789`
   * JP: `+81 123 45 6789`

## Formatting Behavior [#formatting-behavior]

The component automatically handles phone number formatting based on whether a country is selected.

* When no country is selected, it uses international format with country code by default.
* When a country is selected, it uses national format by default.

The formatting behavior can be configured to suit different use cases.

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/phone-input-primitive
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui/react @base-ui/utils react-phone-number-input
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="phone-input-primitive" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Anatomy [#anatomy]

```tsx
import * as PhoneInputPrimitive from "@/components/ui/phone-input-primitive";

export default () => (
  <PhoneInputPrimitive.Root>
    <PhoneInputPrimitive.CountrySelect>
      <PhoneInputPrimitive.CountrySelectOption />
    </PhoneInputPrimitive.CountrySelect>
    <PhoneInputPrimitive.Input />
  </PhoneInputPrimitive.Root>
);
```

## Examples [#examples]

### Default [#default]

Basic example with country select and input.

<ComponentPreview name="phone-input-primitive-demo" />

### Disabled [#disabled]

<ComponentPreview name="phone-input-primitive-disabled" />

### Preferred Country [#preferred-country]

When you know the likely country of your users (such as for a local business signup), you can set a default country while still allowing international numbers. This lets users enter phone numbers in their national format for the default country, while maintaining the flexibility to use international formats for any other country.

In this example, the default country is set to Malaysia, with the initial value forced to display in international format rather than the default national format.

<ComponentPreview name="phone-input-primitive-preferred-country" />

<Callout className="mt-4 border-amber-200 bg-amber-50 dark:border-amber-950 dark:bg-amber-950/50 [&_[data-slot=alert-description]]:text-foreground">
  **Important**: Since `react-phone-number-input` uses a function-based approach for its `inputComponent` prop, this differs from Base UI's `render` composition which expects a JSX element directly.

  To ensure stable behavior and prevent focus issues, it's recommended to always wrap your `render` element with `useMemo` to maintain a stable reference. Avoid passing inline elements without `useMemo`, as this will cause focus issues on each change.
</Callout>

## API Reference [#api-reference]

### Root [#root]

Manages the phone value and selected country and provides them to the parts below. Renders no element of its own.

| Prop                                      | Type                                 | Default | Description                                                                                                                                                             |
| ----------------------------------------- | ------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`                                   | `Value`                              | -       | The phone number in E.164 format (e.g. `"+12133734253"`). Use for controlled value.                                                                                     |
| `defaultValue`                            | `Value`                              | `""`    | The initial value when uncontrolled.                                                                                                                                    |
| `onValueChange`                           | `(value: Value) => void`             | -       | Called when the phone number changes.                                                                                                                                   |
| `country`                                 | `Country \| null`                    | -       | The selected country. `null` means "International". Use for controlled country.                                                                                         |
| `defaultCountry`                          | `Country`                            | -       | The initial country when uncontrolled.                                                                                                                                  |
| `onCountryChange`                         | `(country: Country \| null) => void` | -       | Called when the selected country changes.                                                                                                                               |
| `preferredCountry`                        | `Country`                            | -       | Suggests a country while no country is selected: numbers can be typed in this country's national format while international numbers for any other country keep working. |
| `defaultInternationalForPreferredCountry` | `boolean`                            | `false` | Forces international format for initial values that match the preferred country. Only valid together with `preferredCountry`.                                           |
| `international`                           | `boolean`                            | `false` | Forces international format when a country is explicitly selected.                                                                                                      |
| `withCountryCallingCode`                  | `boolean`                            | `false` | Keeps the country calling code visible and undeletable in international format. Only valid together with `international`.                                               |
| `disabled`                                | `boolean`                            | `false` | Disables the input and the country select.                                                                                                                              |
| `children`                                | `ReactNode`                          | -       | The phone input parts.                                                                                                                                                  |

### Input [#input]

The phone number input, formatting as you type via [react-phone-number-input](https://catamphetamine.gitlab.io/react-phone-number-input/). Renders an `<input>` by default.

| Prop         | Type                                           | Default | Description                                                                                                             |
| ------------ | ---------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `render`     | `ReactElement`                                 | -       | Render as a different input element. Wrap it in `useMemo` — see the callout above.                                      |
| `smartCaret` | `boolean`                                      | `true`  | Keeps the caret position stable while the value is reformatted.                                                         |
| `...props`   | `React.ComponentProps<typeof ReactPhoneInput>` | -       | Remaining [react-phone-number-input props](https://catamphetamine.gitlab.io/react-phone-number-input/docs/) are spread. |

### CountrySelect [#countryselect]

The country selector. Renders a native `<select>` wired to the country state.

| Prop       | Type                             | Default | Description                         |
| ---------- | -------------------------------- | ------- | ----------------------------------- |
| `...props` | `React.ComponentProps<"select">` | -       | Props spread to the select element. |

### CountrySelectOption [#countryselectoption]

A country option. Renders an `<option>`.

| Prop       | Type                             | Default | Description                         |
| ---------- | -------------------------------- | ------- | ----------------------------------- |
| `...props` | `React.ComponentProps<"option">` | -       | Props spread to the option element. |

### CountryInternationalSelectOption [#countryinternationalselectoption]

The "International" option. Selecting it clears the country (`null`).

| Prop       | Type                                            | Default | Description                         |
| ---------- | ----------------------------------------------- | ------- | ----------------------------------- |
| `...props` | `Omit<React.ComponentProps<"option">, "value">` | -       | Props spread to the option element. |

### getCountryOptions [#getcountryoptions]

A helper that returns `{ countryCode, countryCallingCode }` for every supported country — useful for rendering the options list.

### usePhoneInput [#usephoneinput]

Hook exposing the phone input context (`value`, `country`, change handlers, `disabled`) for building custom parts. Must be used within `<PhoneInput.Root>`.

# Sortable (/docs/utilities/sortable)

<ComponentPreview name="sortable-demo" />

## About [#about]

The `<Sortable />` component is built on top of [@dnd-kit](https://dndkit.com)'s [sortable](https://docs.dndkit.com/presets/sortable) preset.

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/sortable
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities @base-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="sortable" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Usage [#usage]

```tsx
import {
  Sortable,
  SortableGrid,
  SortableItem,
  SortableItemTrigger,
  SortableList,
  SortableOverlay,
} from "@/components/ui/sortable";
```

```tsx
<Sortable>
  <SortableList>
    <SortableItem>
      <SortableItemTrigger />
    </SortableItem>
  </SortableList>
  <SortableGrid>
    <SortableItem>
      <SortableItemTrigger />
    </SortableItem>
  </SortableGrid>
  <SortableOverlay />
</Sortable>
```

## Examples [#examples]

### Default [#default]

<ComponentPreview name="sortable-demo" />

### Trigger [#trigger]

<ComponentPreview name="sortable-trigger" />

### Disabled [#disabled]

<ComponentPreview name="sortable-disabled" />

### Swap [#swap]

<ComponentPreview name="sortable-swap" />

### Form [#form]

<ComponentPreview name="sortable-form" />

### Virtualized [#virtualized]

<ComponentPreview name="virtualized-sortable" />

## Accessibility [#accessibility]

Keyboard sorting is preconfigured through @dnd-kit's [KeyboardSensor](https://docs.dndkit.com/api-documentation/sensors/keyboard): focus an item (or its `<SortableItemTrigger />` handle), press <Kbd>Enter</Kbd> or <Kbd>Space</Kbd> to pick it up, move it with the arrow keys, then press <Kbd>Enter</Kbd> or <Kbd>Space</Kbd> again to drop it or <Kbd>Escape</Kbd> to cancel.

Screen reader announcements ("Picked up sortable item…") are provided by @dnd-kit and can be customized via the `accessibility` prop on `<Sortable />` — see the [@dnd-kit accessibility guide](https://docs.dndkit.com/guides/accessibility).

When items are only draggable via a handle, keep the `<SortableItemTrigger />` a real `<button>` (the default) so it is focusable, and give icon-only handles an accessible name, e.g. `aria-label="Reorder"`.

## API Reference [#api-reference]

### Sortable [#sortable]

The root context. Wraps @dnd-kit's [DndContext](https://docs.dndkit.com/api-documentation/context-provider) with pointer and keyboard sensors and `closestCenter` collision detection preconfigured. Handle reordering in `onDragEnd`.

| Prop                 | Type                                                    | Default                  | Description                                                                                      |
| -------------------- | ------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
| `getNewIndex`        | `NewIndexGetter`                                        | -                        | Computes the index an item moves to when sorting with the keyboard, e.g. for swap-based sorting. |
| `getTransformStyle`  | `(transform: Transform \| null) => string \| undefined` | `CSS.Transform.toString` | Converts an item's transform into its CSS `transform` style.                                     |
| `collisionDetection` | `CollisionDetection`                                    | `closestCenter`          | The collision detection algorithm.                                                               |
| `...props`           | `DndContextProps`                                       | -                        | Props spread to [DndContext](https://docs.dndkit.com/api-documentation/context-provider#props).  |

### SortableList [#sortablelist]

A sortable list. Wraps @dnd-kit's [SortableContext](https://docs.dndkit.com/presets/sortable/sortable-context) and renders a `<ul>`.

| Prop          | Type                             | Default                    | Description                                                                                                                                |
| ------------- | -------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `items`       | `(UniqueIdentifier \| { id })[]` | -                          | The sorted item identifiers, in render order.                                                                                              |
| `orientation` | `"vertical" \| "horizontal"`     | `"vertical"`               | The layout direction of the list.                                                                                                          |
| `strategy`    | `SortingStrategy`                | Derived from `orientation` | The [sorting strategy](https://docs.dndkit.com/presets/sortable#sorting-strategies); defaults to the vertical or horizontal list strategy. |
| `disabled`    | `boolean \| Disabled`            | -                          | Disables sorting for the whole list.                                                                                                       |
| `render`      | `ReactElement \| function`       | -                          | Render as a different element.                                                                                                             |
| `...props`    | `React.ComponentProps<"ul">`     | -                          | Props spread to the list element.                                                                                                          |

### SortableGrid [#sortablegrid]

A sortable grid. Same as `<SortableList />` but renders a `<div>` and defaults to @dnd-kit's `rectSortingStrategy`, which suits grid layouts.

| Prop       | Type                             | Default               | Description                                   |
| ---------- | -------------------------------- | --------------------- | --------------------------------------------- |
| `items`    | `(UniqueIdentifier \| { id })[]` | -                     | The sorted item identifiers, in render order. |
| `strategy` | `SortingStrategy`                | `rectSortingStrategy` | The sorting strategy.                         |
| `disabled` | `boolean \| Disabled`            | -                     | Disables sorting for the whole grid.          |
| `render`   | `ReactElement \| function`       | -                     | Render as a different element.                |
| `...props` | `React.ComponentProps<"div">`    | -                     | Props spread to the grid element.             |

### SortableItem [#sortableitem]

A sortable item. Renders a `<div>` that is draggable as a whole unless a `<SortableItemTrigger />` handle is present. Exposes `data-dragging`, `data-over` and `data-sorting` attributes for styling.

| Prop       | Type                          | Default | Description                                                                |
| ---------- | ----------------------------- | ------- | -------------------------------------------------------------------------- |
| `id`       | `UniqueIdentifier`            | -       | The item's unique identifier. Must match an entry in the parent's `items`. |
| `disabled` | `boolean \| Disabled`         | -       | Disables sorting for this item.                                            |
| `render`   | `ReactElement \| function`    | -       | Render as a different element.                                             |
| `...props` | `React.ComponentProps<"div">` | -       | Props spread to the item element.                                          |

### SortableItemTrigger [#sortableitemtrigger]

A drag handle. Renders a `<button>`; when present, dragging (pointer and keyboard) starts from the handle instead of the whole item. Exposes the same `data-dragging`, `data-over` and `data-sorting` attributes.

| Prop       | Type                             | Default | Description                         |
| ---------- | -------------------------------- | ------- | ----------------------------------- |
| `disabled` | `boolean`                        | -       | Disables the handle.                |
| `render`   | `ReactElement \| function`       | -       | Render as a different element.      |
| `...props` | `React.ComponentProps<"button">` | -       | Props spread to the handle element. |

### SortableOverlay [#sortableoverlay]

The drag preview. Wraps @dnd-kit's [DragOverlay](https://docs.dndkit.com/api-documentation/draggable/drag-overlay) in a portal to `document.body` and renders its children only while an item is being dragged.

| Prop       | Type                                               | Default | Description                                                                                            |
| ---------- | -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `children` | `ReactNode \| (id: UniqueIdentifier) => ReactNode` | -       | The preview content; the function form receives the active item's identifier.                          |
| `...props` | `React.ComponentProps<typeof DragOverlay>`         | -       | Props spread to [DragOverlay](https://docs.dndkit.com/api-documentation/draggable/drag-overlay#props). |

# Virtualized (/docs/utilities/virtualized)

<ComponentPreview name="virtualized-demo" />

## Introduction [#introduction]

Efficiently rendering large lists and tabular data is a common challenge in UI development. By leveraging [virtualization](https://www.patterns.dev/vanilla/virtual-lists/), we can significantly enhance performance.

<figure className="flex flex-col gap-4">
  <Image src="/images/list-virtualization-light.png" width="1135" height="1135" alt="List Virtualization" className="mt-6 w-full overflow-hidden rounded-lg border shadow-sm dark:hidden" />

  <Image src="/images/list-virtualization-dark.png" width="1135" height="1135" alt="List Virtualization" className="mt-6 hidden w-full overflow-hidden rounded-lg border shadow-sm dark:block" />

  <figcaption className="text-center text-sm text-gray-500">
    Rendering only visible rows of content in a dynamic list instead of the
    entire list using virtualization.
  </figcaption>
</figure>

After exploring various libraries, I found [virtua](https://github.com/inokawa/virtua) to be one of the most intuitive and effective choices. Its straightforward API allows seamless integration with other tools like [@dnd-kit](https://dndkit.com) and [Base UI](https://base-ui.com), making it easy to virtualize different components effectively.

This documentation serves as a guide to help you understand how to use the `<Virtualized />` component. Feel free to create your own abstraction of the virtualized components, e.g. `<VirtualizedScrollArea />`, `<VirtualizedSelect />`, etc.

<Callout className="mt-4 bg-amber-50 border-amber-200 dark:bg-amber-950/50 dark:border-amber-950 [&_[data-slot=alert-description]]:text-foreground">
  **Important**: Use virtualization judiciously. It's best suited for scenarios involving large lists or tables, rather than squeezing out every bit of "performance optimizations".
</Callout>

## Installation [#installation]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add junwen-k/ui-x/virtualized
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui/react virtua
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="virtualized" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Examples [#examples]

### Default [#default]

<ComponentPreview name="virtualized-demo" />

### Horizontal [#horizontal]

<ComponentPreview name="virtualized-horizontal" />

### Grid [#grid]

<ComponentPreview name="virtualized-grid" />

### Table [#table]

<ComponentPreview name="virtualized-table" />

<Callout className="mt-6">
  **Note:** Until virtua improves its support for [table virtualization](https://github.com/inokawa/virtua/issues/312), you will need to manually set the cell width because of the current use of absolute positioning.
</Callout>

### Command [#command]

<ComponentPreview name="virtualized-command" />

### Combobox [#combobox]

<ComponentPreview name="virtualized-combobox" />

### Select [#select]

<ComponentPreview name="virtualized-select" />

### Scroll Area [#scroll-area]

<ComponentPreview name="virtualized-scroll-area" />

### Sortable [#sortable]

<ComponentPreview name="virtualized-sortable" />

## Combobox [#combobox-1]

To virtualize a `<Combobox />` component, you'll need to use `<Virtualized />` component.

<Steps>
  ### Setup `scollRef` [#setup-scollref]

  Attach the `scrollRef` to the `<ComboboxContent />` with `<Virtualized />`, as it serves as the scrollable container:

  ```tsx showLineNumbers {5,7,9}
  export function VirtualizedComboboxDemo() {
    return (
      <Combobox>
        {/* ... */}
        <Virtualized render={<ComboboxContent />}>
          {/* ... */}
          <VirtualizedVirtualizer>{/* ... */}</VirtualizedVirtualizer>
          {/* ... */}
        </Virtualized>
      </Combobox>
    );
  }
  ```

  ### Handle filtering [#handle-filtering]

  Control the `inputValue` and pass `shouldFilter={false}` to the `<Combobox />`, as the default filtering does not support virtualization. You will also need to filter items manually:

  ```tsx showLineNumbers {3,5-13,18-20}
  export function VirtualizedComboboxDemo() {
    // ...
    const [inputValue, setInputValue] = React.useState("");

    const filtered = React.useMemo(() => {
      if (!inputValue) {
        return items;
      }

      return items.filter((item) =>
        item.label.toLowerCase().includes(inputValue.toLowerCase()),
      );
    }, [inputValue]);

    return (
      <Combobox
        // ...
        shouldFilter={false}
        inputValue={inputValue}
        onInputValueChange={setInputValue}
        // ...
      >
        {/* ... */}
      </Combobox>
    );
  }
  ```

  <Callout className="mt-4">
    **Tip**: You may also fetch your items with debounced `inputValue` from API calls.
  </Callout>
</Steps>

<ComponentPreview name="virtualized-combobox" />

<Callout className="mt-4">
  **Tip**: If you use `<ComboboxGroup />` with `heading`, you'll need to set the `startMargin` to match the heading's height. This ensures that the virtualized viewport is positioned correctly within the `<PopoverContent />`.
</Callout>

## Scroll Area [#scroll-area-1]

To virtualize a `<ScrollArea />` component, you'll need to use the [primitive](https://base-ui.com/react/components/scroll-area) components directly. shadcn/ui's version includes its own abstraction, which does not support virtualization out of the box.

<Steps>
  ### Setup `scrollRef` [#setup-scrollref]

  Attach the `scrollRef` to the `<ScrollAreaPrimitive.Viewport />` by rendering it as `<Virtualized />`, as it serves as the scrollable container:

  ```tsx showLineNumbers {4-7}
  export function VirtualizedScrollAreaDemo() {
    return (
      <ScrollAreaPrimitive.Root className="relative h-72 w-48 overflow-hidden rounded-md border">
        <ScrollAreaPrimitive.Viewport
          render={<Virtualized />}
          className="size-full rounded-[inherit]"
        >
          {/* ... */}
          <VirtualizedVirtualizer>{/* ... */}</VirtualizedVirtualizer>
          {/* ... */}
        </ScrollAreaPrimitive.Viewport>
        <ScrollBar />
        <ScrollAreaPrimitive.Corner />
      </ScrollAreaPrimitive.Root>
    );
  }
  ```
</Steps>

<ComponentPreview name="virtualized-scroll-area" />

<Callout className="mt-4">
  **Tip:** As usual, double-check to see if you need to set the `startMargin`.
</Callout>

## Select [#select-1]

To virtualize a `<Select />` component, render its `<SelectContent />` as a `<Virtualized />` viewport. Since the virtualized viewport manages its own scrolling, set `alignItemWithTrigger={false}` so the content is positioned like a popover:

<Steps>
  ### Setup `scrollRef` [#setup-scrollref-1]

  Attach the `scrollRef` to the `<SelectContent />` by rendering it as `<Virtualized />`, as it serves as the scrollable container:

  ```tsx showLineNumbers {5-9}
  export function VirtualizedSelectDemo() {
    return (
      <Select items={items}>
        {/* ... */}
        <SelectContent
          alignItemWithTrigger={false}
          className="max-h-96"
          render={<Virtualized />}
        >
          <VirtualizedVirtualizer>{/* ... */}</VirtualizedVirtualizer>
        </SelectContent>
      </Select>
    );
  }
  ```

  ### Handle scroll position and focus [#handle-scroll-position-and-focus]

  To replicate the scroll position and focus behavior of `<Select />`, manage the `open` and `value` states, and access the virtualizer instance using imperative methods with the `ref`:

  ```tsx showLineNumbers {2-3,5-6,8-11,13-27,31-34,38,40}
  export function VirtualizedSelectDemo() {
    const [value, setValue] = React.useState<string | null>(null);
    const [open, setOpen] = React.useState(false);

    const virtualizerRef = React.useRef<VirtualizerHandle>(null);
    const viewportRef = React.useRef<HTMLDivElement>(null);

    const activeIndex = React.useMemo(
      () => items.findIndex((item) => item.value === value),
      [value],
    );

    React.useLayoutEffect(() => {
      if (!open || !value || activeIndex === -1) return;

      setTimeout(() => {
        // Recover scroll position.
        virtualizerRef.current?.scrollToIndex(activeIndex, { align: "end" });

        const selectedElement = viewportRef.current?.querySelector(
          "[data-selected]",
        ) as HTMLElement;

        // Recover focus.
        selectedElement?.focus({ preventScroll: true });
      });
    }, [open, value, activeIndex]);

    return (
      <Select
        open={open}
        onOpenChange={setOpen}
        value={value}
        onValueChange={setValue}
      >
        {/* ... */}
        <SelectContent render={<Virtualized ref={viewportRef} />}>
          <VirtualizedVirtualizer ref={virtualizerRef}>
            {/* ... */}
          </VirtualizedVirtualizer>
        </SelectContent>
        {/* ... */}
      </Select>
    );
  }
  ```

  ### Ensure active item is always mounted [#ensure-active-item-is-always-mounted]

  To ensure the selected item is rendered within the `<SelectTrigger />`, use the `keepMounted` prop:

  ```tsx showLineNumbers {11}
  export function VirtualizedSelectDemo() {
    // ...

    return (
      <Select
      // ...
      >
        {/* ... */}
        <VirtualizedVirtualizer
          // ...
          keepMounted={activeIndex !== -1 ? [activeIndex] : undefined}
        >
          {/* ... */}
        </VirtualizedVirtualizer>
        {/* ... */}
      </Select>
    );
  }
  ```
</Steps>

<ComponentPreview name="virtualized-select" />

## Reusable Components [#reusable-components]

### Virtualized Select [#virtualized-select]

<Callout className="mt-4">
  This section is empty for now.
</Callout>

## Accessibility [#accessibility]

Virtualization only affects what's mounted in the DOM, not the semantics of the component being virtualized — a virtualized `<Select />` or `<Combobox />` keeps the same roles, states and keyboard behavior as its non-virtualized counterpart, since `<VirtualizedVirtualizer />` renders its children directly inside the existing listbox/popover markup.

Because off-screen items aren't in the DOM, avoid relying on browser "find in page" or assistive technology virtual cursor navigation to reach items outside the rendered window — users should navigate with the component's own keyboard interactions (arrow keys, typeahead) instead, which keep the active item mounted and in view via `keepMounted` and `scrollToIndex`.

## API Reference [#api-reference]

Thin wrappers around [virtua](https://github.com/inokawa/virtua) — see the [virtua API reference](https://github.com/inokawa/virtua/blob/main/docs/react/API.md) for the full list of underlying props and imperative handle methods.

### Virtualized [#virtualized]

The scrollable container. Renders a `<div>` and provides its scroll ref to a `<VirtualizedVirtualizer />` inside. Use the `render` prop to attach the scroll container to an existing component, e.g. `render={<ComboboxContent />}`.

| Prop       | Type                          | Default | Description                            |
| ---------- | ----------------------------- | ------- | -------------------------------------- |
| `render`   | `ReactElement \| function`    | -       | Render as a different element.         |
| `...props` | `React.ComponentProps<"div">` | -       | Props spread to the container element. |

### VirtualizedList [#virtualizedlist]

A standalone virtualized list that scrolls itself. Wraps virtua's [VList](https://github.com/inokawa/virtua/blob/main/docs/react/API.md#vlist) and accepts all of its props (`keepMounted`, `shift`, imperative `ref`, …). Must not be used within a `<Virtualized />` — use `<VirtualizedVirtualizer />` there instead.

| Prop          | Type                                 | Default      | Description                       |
| ------------- | ------------------------------------ | ------------ | --------------------------------- |
| `orientation` | `"vertical" \| "horizontal"`         | `"vertical"` | The scroll direction of the list. |
| `...props`    | `React.ComponentProps<typeof VList>` | -            | Props spread to virtua's `VList`. |

### VirtualizedGrid [#virtualizedgrid]

A virtualized grid that virtualizes both rows and columns. Wraps virtua's experimental [VGrid](https://github.com/inokawa/virtua/blob/main/docs/react/API.md#experimental_vgrid) and accepts all of its props (`row`, `col`, `cellHeight`, `cellWidth`, …).

### VirtualizedVirtualizer [#virtualizedvirtualizer]

The virtualized viewport for a `<Virtualized />` container. Wraps virtua's [Virtualizer](https://github.com/inokawa/virtua/blob/main/docs/react/API.md#virtualizer) with `scrollRef` already wired to the surrounding `<Virtualized />`, and accepts all of its remaining props (`startMargin`, `keepMounted`, imperative `ref`, …).

# BProgress (/docs/components/bprogress)

<div className="grid gap-4 sm:grid-cols-2 sm:gap-6">
  <NextjsLinkedCard href="/docs/components/bprogress/next" />
</div>

# Next.js (/docs/components/bprogress/next)

## App Router [#app-router]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <Steps>
      <Step>
        Run the following command:
      </Step>

      ```bash
      npx shadcn@latest add junwen-k/ui-x/bprogress-provider-next-app
      ```

      <Step>
        Wrap your root layout with the `<BProgressProvider />` component:
      </Step>

      ```tsx title="app/layout.tsx" showLineNumbers {1,8}
      import { BProgressProvider } from "@/components/bprogress-provider";

      export default function RootLayout({ children }: RootLayoutProps) {
        return (
          <html lang="en">
            <head />
            <body>
              <BProgressProvider>{children}</BProgressProvider>
            </body>
          </html>
        );
      }
      ```
    </Steps>
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @bprogress/next
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource type="components" name="bprogress-provider-next-app" />

      <Step>
        Update the import paths to match your project setup.
      </Step>

      <Step>
        Wrap your root layout with the `<BProgressProvider />` component:
      </Step>

      ```tsx title="app/layout.tsx" showLineNumbers {1,8}
      import { BProgressProvider } from "@/components/bprogress-provider";

      export default function RootLayout({ children }: RootLayoutProps) {
        return (
          <html lang="en">
            <head />
            <body>
              <BProgressProvider>{children}</BProgressProvider>
            </body>
          </html>
        );
      }
      ```
    </Steps>
  </TabsContent>
</Tabs>

## Pages Router [#pages-router]

<Tabs defaultValue="cli">
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <Steps>
      <Step>
        Run the following command:
      </Step>

      ```bash
      npx shadcn@latest add junwen-k/ui-x/bprogress-provider-next-pages
      ```

      <Step>
        Wrap your root layout with the `<BProgressProvider />` component:
      </Step>

      ```tsx title="pages/_app.tsx" showLineNumbers {1,5,7}
      import { BProgressProvider } from "@/components/bprogress-provider";

      export default function App({ Component, pageProps }: AppProps) {
        return (
          <BProgressProvider>
            <Component {...pageProps} />
          </BProgressProvider>
        );
      }
      ```
    </Steps>
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @bprogress/next
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource type="components" name="bprogress-provider-next-pages" />

      <Step>
        Update the import paths to match your project setup.
      </Step>

      <Step>
        Wrap your root layout with the `<BProgressProvider />` component:
      </Step>

      ```tsx title="pages/_app.tsx" showLineNumbers {1,5,7}
      import { BProgressProvider } from "@/components/bprogress-provider";

      export default function App({ Component, pageProps }: AppProps) {
        return (
          <BProgressProvider>
            <Component {...pageProps} />
          </BProgressProvider>
        );
      }
      ```
    </Steps>
  </TabsContent>
</Tabs>

## API Reference [#api-reference]

### BProgressProvider [#bprogressprovider]

Wraps `@bprogress/next`'s progress provider (`AppProgressProvider` for the App Router, `PagesProgressProvider` for the Pages Router) with theme-aware defaults, and accepts all of its props — see the [BProgress provider documentation](https://bprogress.vercel.app/docs/next/app-dir/provider) for the full list.

| Prop             | Type                    | Default                         | Description                                                         |
| ---------------- | ----------------------- | ------------------------------- | ------------------------------------------------------------------- |
| `color`          | `string`                | `"var(--primary)"`              | The progress bar color.                                             |
| `height`         | `string`                | `"calc(var(--spacing) * 0.75)"` | The progress bar height.                                            |
| `options`        | `ProgressOptions`       | `{ showSpinner: false }`        | [BProgress options](https://bprogress.vercel.app/docs/api#options). |
| `shallowRouting` | `boolean`               | `true`                          | Skips the progress bar when only search params change.              |
| `...props`       | `ProgressProviderProps` | -                               | Props spread to the underlying provider.                            |