> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/date-range-picker.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# DateRangePicker

Choose a date, datetime or time range. Calendar modes use local `Date` tuples; time-only mode uses string tuples. Use [DatePicker](https://ifhover.github.io/leaf-ui/en/components/date-picker.md) for a single value.


## Basic usage

Select the start, then the end to commit a complete range and close the panel. Date mode supports reversed selection and orders the result from start to end. Set an initial uncontrolled range with `defaultValue`.


Date range

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-range-picker/basic.tsx"
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerBasic() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Date range">
        <DateRangePicker />
      </FormField>
    </Form>
  );
}
```

Expand code


## Examples

### Controlled value and selection progress

`onChange` receives the committed range and two formatted strings; clearing returns `null` and `['', '']`. `onCalendarChange` observes panel-selection drafts and the edited endpoint, not a committed range, and does not cover every text or preset change. Update application state when resetting a controlled field.


Controlled date range

Committed: 2026-10-05 ~ 2026-10-09Latest panel edit: Not adjustedReset

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-range-picker/controlled.tsx"
import { Button, type DateRange, DateRangePicker, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const initialRange: DateRange = [new Date(2026, 9, 5), new Date(2026, 9, 9)];

function formatDate(date: Date | null) {
  if (!date) return '-';
  return [date.getFullYear(), date.getMonth() + 1, date.getDate()]
    .map((part, index) => (index === 0 ? String(part) : String(part).padStart(2, '0')))
    .join('-');
}

export function DateRangePickerControlled() {
  const [value, setValue] = useState<DateRange | null>(initialRange);
  const [committed, setCommitted] = useState('2026-10-05 ~ 2026-10-09');
  const [draft, setDraft] = useState('Not adjusted');

  return (
    <Form
      layout="vertical"
      onSubmit={(event) => event.preventDefault()}
      onReset={() => {
        setValue(initialRange);
        setCommitted('2026-10-05 ~ 2026-10-09');
        setDraft('Not adjusted');
      }}
    >
      <FormField label="Controlled date range">
        <DateRangePicker
          value={value}
          onChange={(next: DateRange | null, texts: readonly [string, string]) => {
            setValue(next);
            setCommitted(next ? texts.join(' ~ ') : 'Empty');
          }}
          onCalendarChange={(next, { position }) => {
            setDraft(`${position}: ${next.map(formatDate).join(' ~ ')}`);
          }}
        />
      </FormField>
      <Text tone="muted" role="status">
        Committed: {committed}
      </Text>
      <Text tone="muted" role="status">
        Latest panel edit: {draft}
      </Text>
      <Button type="reset">Reset</Button>
    </Form>
  );
}
```

Expand code

### Picker modes

Set `picker` to select years, quarters, months or weeks. Both `Date` values represent the start of their period. [ConfigProvider](https://ifhover.github.io/leaf-ui/en/components/config-provider.md) sets the first weekday with `weekStartsOn`, defaulting to Monday.


Year range

Quarter range

Month range

Week range

modes.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-range-picker/modes.tsx"
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerModes() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Year range">
        <DateRangePicker picker="year" />
      </FormField>
      <FormField label="Quarter range">
        <DateRangePicker picker="quarter" />
      </FormField>
      <FormField label="Month range">
        <DateRangePicker picker="month" />
      </FormField>
      <FormField label="Week range">
        <DateRangePicker picker="week" />
      </FormField>
    </Form>
  );
}
```

Expand code

### Date-time ranges

With `picker="datetime"`, choose the start date and time, select Next to edit the end, then OK to commit. The datetime panel requires the end not to precede the start. `defaultTime` supplies times for newly picked endpoints, not an initial range.


Booking window

datetime.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-range-picker/datetime.tsx"
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerDateTime() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Booking window">
        <DateRangePicker picker="datetime" defaultTime={['09:00', '18:00']} minuteStep={15} />
      </FormField>
    </Form>
  );
}
```

Expand code

This mode defaults to `needConfirm={true}` and discards an unconfirmed range on outside clicks. Other calendar modes commit after choosing an end by default; set `needConfirm` to require confirmation. Escape discards the current edit. Clearing or choosing a valid preset commits directly.

### Restrict selectable endpoints

`minDate` / `maxDate` include their boundaries. `disabledDate` receives `position` to distinguish start and end. This example restricts endpoints to October and excludes Sundays as endpoints; a range may still span a Sunday. Validate whole-range availability in the application if required.


October delivery window

disabled-dates.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-range-picker/disabled-dates.tsx"
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DisabledDates() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="October delivery window">
        <DateRangePicker
          defaultValue={[new Date(2026, 9, 5), new Date(2026, 9, 9)]}
          minDate={new Date(2026, 9, 1)}
          maxDate={new Date(2026, 9, 31)}
          disabledDate={(date) => date.getDay() === 0}
        />
      </FormField>
    </Form>
  );
}
```

Expand code

Restrictions apply to typing and panel selection without clearing existing values. Datetime bounds compare complete timestamps; `disabledTime` receives time parts, endpoint position and the current date. `inputReadOnly` prevents typing, while `readOnly` prevents changes.

### Open endpoints

`allowEmpty` permits empty endpoints independently. This example uses `[false, true]` for a required start and optional end, with `OpenDateRange` imported from the root entry. At least one endpoint must remain non-empty; use `null`, not `[null, null]`, to clear the whole control.


Ongoing project period

Start: 2026-10-05; end: Empty

open-end.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-range-picker/open-end.tsx"
import { DateRangePicker, Form, FormField, type OpenDateRange, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function OpenEnd() {
  const [value, setValue] = useState<OpenDateRange | null>([new Date(2026, 9, 5), null]);
  const [texts, setTexts] = useState<readonly [string, string]>(['2026-10-05', '']);

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Ongoing project period">
        <DateRangePicker
          allowEmpty={[false, true]}
          value={value}
          onChange={(next: OpenDateRange | null, dateStrings: readonly [string, string]) => {
            setValue(next);
            setTexts(dateStrings);
          }}
        />
      </FormField>
      <Text tone="muted" role="status">
        Start: {texts[0] || 'Empty'}; end: {texts[1] || 'Empty'}
      </Text>
    </Form>
  );
}
```

Expand code

Clear an allowed endpoint with the panel footer action; its callback string is `''`. Opening with only a start continues editing the end.

### Time range

With `picker="time"`, values and callbacks use `['HH:mm', 'HH:mm']` or `null`, or `HH:mm:ss` with `showSeconds`. `use12Hours` changes display only; values stay in 24-hour format. `minTime` / `maxTime` apply to both endpoints. Time-only mode does not support `allowEmpty`.


Working hours

Current value: 09:00 ~ 18:00

time.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-range-picker/time.tsx"
import { DateRangePicker, Form, FormField, Text, type TimeRange } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DateRangePickerTime() {
  const [value, setValue] = useState<TimeRange | null>(['09:00', '18:00']);

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Working hours">
        <DateRangePicker picker="time" value={value} onChange={setValue} />
      </FormField>
      <Text tone="muted" role="status">
        Current value: {value ? value.join(' ~ ') : 'Empty'}
      </Text>
    </Form>
  );
}
```

Expand code

### Across midnight

By default, the end must not precede the start. Set `allowOvernight` to allow 22:00 to 06:00 the next day without swapping endpoints. Time mode commits valid changes on dismissal by default; set `needConfirm` to require explicit confirmation.


Overnight shift

overnight.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-range-picker/overnight.tsx"
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerOvernight() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Overnight shift">
        <DateRangePicker picker="time" allowOvernight defaultValue={['22:00', '06:00']} />
      </FormField>
    </Form>
  );
}
```

Expand code

### Range shortcuts

[](#)
`presets` provides common ranges, previewed on hover or focus. Choosing a valid range commits it immediately and closes the panel. `value` may be a range or a function returning one synchronously, not a Promise. Functions may run multiple times and must have no side effects.


Reporting range

presets.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-range-picker/presets.tsx"
import { type DateRange, DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

function recentSevenDays(): DateRange {
  const end = new Date();
  end.setHours(0, 0, 0, 0);
  const start = new Date(end);
  start.setDate(start.getDate() - 6);
  return [start, end];
}

export function Presets() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Reporting range">
        <DateRangePicker presets={[{ label: 'Recent 7 days', value: recentSevenDays }]} />
      </FormField>
    </Form>
  );
}
```

Expand code

### Display format and form submission

A custom `format` changes display and the string tuple passed to `onChange`. FormData retains canonical formats joined as `start/end`. This example displays `DD/MM/YYYY` and submits a value such as `2026-10-05/2026-10-09`; an open end produces `2026-10-05/`, and clearing produces an empty string. Resetting an uncontrolled field restores `defaultValue`.


Reporting period

SubmitReset

FormData: Not submitted

form.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/date-range-picker/form.tsx"
import { Button, DateRangePicker, Form, FormField, Space, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DateRangePickerForm() {
  const [submitted, setSubmitted] = useState<string | null>(null);

  return (
    <Form
      layout="vertical"
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(String(new FormData(event.currentTarget).get('reportingRange') ?? ''));
      }}
      onReset={() => setSubmitted(null)}
    >
      <FormField label="Reporting period">
        <DateRangePicker
          name="reportingRange"
          format="DD/MM/YYYY"
          defaultValue={[new Date(2026, 9, 5), new Date(2026, 9, 9)]}
        />
      </FormField>
      <Space>
        <Button type="submit">Submit</Button>
        <Button type="reset">Reset</Button>
      </Space>
      <Text tone="muted" role="status">
        FormData: {submitted === null ? 'Not submitted' : JSON.stringify(submitted)}
      </Text>
    </Form>
  );
}
```

Expand code

For canonical period/datetime formats and custom `parse`, see [DatePicker: display format and form submission](https://ifhover.github.io/leaf-ui/en/components/date-picker.md#display-format-and-form-submission). Dates are local calendar values; handle business timezone conversion in the application. See [Form](https://ifhover.github.io/leaf-ui/en/components/form.md) for other form configuration.

Paste a complete date range with endpoints separated by `~`. Enter commits valid input. Invalid or incomplete input reverts when focus leaves the whole control; Escape discards the edit. See [DatePicker: input and confirmation](https://ifhover.github.io/leaf-ui/en/components/date-picker.md#input-and-confirmation) for segmented input.


## API

### DateRangePicker API

The main table covers calendar and time-only branches, but not every prop applies to both. `allowEmpty`, `format`, `parse`, `presets`, date bounds and calendar configuration belong to calendar modes; `allowOvernight` and `minTime` / `maxTime` belong to time-only mode.

| Property            | Type                                                                                                                                                                                                                                                                                                     | Default                    | Description                                                                                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `picker`            | `'year' \| 'quarter' \| 'month' \| 'week' \| 'date' \| 'datetime' \| 'time'`                                                                                                                                                                                                                             | `'date'`                   | Select a date, time, date-time, week, month, quarter or year.                                                                                                |
| `value`             | `readonly [Date, Date] \| null \| readonly [Date \| null, Date \| null] \| readonly [string, string]`                                                                                                                                                                                                    | —                          | Controlled range: a Date tuple for date modes, with nullable endpoints when allowEmpty is enabled; a 24-hour string tuple for time. The empty range is null. |
| `defaultValue`      | `readonly [Date, Date] \| null \| readonly [Date \| null, Date \| null] \| readonly [string, string]`                                                                                                                                                                                                    | `null`                     | Initial uncontrolled range matching picker, restored on native form reset.                                                                                   |
| `onChange`          | `(((value: readonly [Date, Date] \| null, dateStrings: readonly [string, string]) => void)) \| (((value: readonly [Date \| null, Date \| null] \| null, dateStrings: readonly [string, string]) => void)) \| ((value: readonly [string, string] \| null) => void)`                                       | —                          | Called when committing a range: Date and string tuples for date modes, a string tuple for time, null on clear.                                               |
| `onCalendarChange`  | `(range: readonly [Date \| null, Date \| null], info: { position: 'start' \| 'end' }) => void`                                                                                                                                                                                                           | —                          | Called for date-panel draft, time and endpoint-clear changes, not a commit; text input and presets do not necessarily call it.                               |
| `allowEmpty`        | `false \| true \| readonly [boolean, boolean]`                                                                                                                                                                                                                                                           | `false`                    | Explicitly allow open range endpoints.                                                                                                                       |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                                                                                                                                                                   | `'md'`                     | Control size                                                                                                                                                 |
| `status`            | `'error' \| 'warning'`                                                                                                                                                                                                                                                                                   | —                          | Validation appearance                                                                                                                                        |
| `disabled`          | `boolean`                                                                                                                                                                                                                                                                                                | `false`                    | Disable interaction.                                                                                                                                         |
| `inputReadOnly`     | `boolean`                                                                                                                                                                                                                                                                                                | —                          | Disable typing while retaining panel selection.                                                                                                              |
| `allowClear`        | `boolean`                                                                                                                                                                                                                                                                                                | `true`                     | Show the clear button                                                                                                                                        |
| `minDate`           | `Date`                                                                                                                                                                                                                                                                                                   | —                          | Earliest / latest allowed values                                                                                                                             |
| `maxDate`           | `Date`                                                                                                                                                                                                                                                                                                   | —                          | Earliest / latest allowed values                                                                                                                             |
| `disabledDate`      | `(date: Date, position: 'start' \| 'end') => boolean`                                                                                                                                                                                                                                                    | —                          | Restrict endpoints, not every date inside the range; position identifies start or end.                                                                       |
| `minTime`           | `string`                                                                                                                                                                                                                                                                                                 | —                          | Earliest selectable time, inclusive, as HH:mm or HH:mm:ss.                                                                                                   |
| `maxTime`           | `string`                                                                                                                                                                                                                                                                                                 | —                          | Latest selectable time, inclusive, as HH:mm or HH:mm:ss.                                                                                                     |
| `disabledTime`      | `((parts: `[`TimeParts`](https://ifhover.github.io/leaf-ui/en/components/date-picker.md#timeparts)`, position: 'start' \| 'end', date: Date) => boolean) \| ((parts: `[`TimeParts`](https://ifhover.github.io/leaf-ui/en/components/date-picker.md#timeparts)`, position: 'start' \| 'end') => boolean)` | —                          | Restrict endpoint times; datetime mode also receives the endpoint Date.                                                                                      |
| `allowOvernight`    | `boolean`                                                                                                                                                                                                                                                                                                | `false`                    | Allow a time-only range to cross midnight.                                                                                                                   |
| `needConfirm`       | `boolean`                                                                                                                                                                                                                                                                                                | `picker === "datetime"`    | Require OK or Enter to commit; discard the draft on blur when enabled.                                                                                       |
| `showSeconds`       | `boolean`                                                                                                                                                                                                                                                                                                | `false`                    | Include seconds in date-time ranges; otherwise seconds are zero                                                                                              |
| `use12Hours`        | `boolean`                                                                                                                                                                                                                                                                                                | `false`                    | Display a 12-hour clock with AM/PM options                                                                                                                   |
| `minuteStep`        | `number`                                                                                                                                                                                                                                                                                                 | `1`                        | Minute segment step and column interval, retaining existing off-step values.                                                                                 |
| `secondStep`        | `number`                                                                                                                                                                                                                                                                                                 | `1`                        | Second segment step and column interval, retaining existing off-step values.                                                                                 |
| `defaultTime`       | `readonly [string, string]`                                                                                                                                                                                                                                                                              | `['00:00:00', '23:59:59']` | Times applied to newly picked start and end dates in datetime mode, as HH:mm\[:ss].                                                                          |
| `format`            | `string \| ((date: Date) => string)`                                                                                                                                                                                                                                                                     | —                          | Display format; dates support YYYY, MM, DD, HH, mm, ss and Q.                                                                                                |
| `parse`             | `(text: string) => Date \| null`                                                                                                                                                                                                                                                                         | —                          | Parse entered text; return null on failure.                                                                                                                  |
| `presets`           | `readonly `[`DatePreset`](https://ifhover.github.io/leaf-ui/en/components/date-picker.md#datepreset)`<readonly [Date \| null, Date \| null]>[]`                                                                                                                                                          | —                          | Presets; value may be computed on demand.                                                                                                                    |
| `panelValue`        | `Date`                                                                                                                                                                                                                                                                                                   | —                          | Controlled date displayed by the calendar panel.                                                                                                             |
| `onPanelChange`     | `(date: Date) => void`                                                                                                                                                                                                                                                                                   | —                          | Called when the displayed calendar period changes.                                                                                                           |
| `cellRender`        | `(date: Date) => ReactNode`                                                                                                                                                                                                                                                                              | —                          | Customize calendar cell content.                                                                                                                             |
| `open`              | `boolean`                                                                                                                                                                                                                                                                                                | —                          | Control whether the panel is open.                                                                                                                           |
| `defaultOpen`       | `boolean`                                                                                                                                                                                                                                                                                                | —                          | Initial open state.                                                                                                                                          |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                                                                                                                                                                | —                          | Called when the panel opens or closes                                                                                                                        |
| `panelVariant`      | `'plain' \| 'card'`                                                                                                                                                                                                                                                                                      | `'plain'`                  | Panel appearance; card places the content on an inset surface above a muted canvas.                                                                          |
| `name`              | `string`                                                                                                                                                                                                                                                                                                 | —                          | Field name in native FormData.                                                                                                                               |
| `form`              | `string`                                                                                                                                                                                                                                                                                                 | —                          | ID of the associated native form.                                                                                                                            |
| `required`          | `boolean`                                                                                                                                                                                                                                                                                                | `false`                    | Require a non-empty value; compound controls validate once.                                                                                                  |
| `popupPlacement`    | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'`                                                                                                                                     | —                          | Placement relative to the trigger.                                                                                                                           |
| `popupClassName`    | `string`                                                                                                                                                                                                                                                                                                 | —                          | Custom class for the popup.                                                                                                                                  |
| `popupStyle`        | `CSSProperties`                                                                                                                                                                                                                                                                                          | —                          | Custom popup styles.                                                                                                                                         |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                                                                                                                                                          | —                          | Wrap or extend popup content; retain the supplied content to preserve interaction.                                                                           |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                                                                                                                                                      | —                          | Return a popup container, including a ShadowRoot.                                                                                                            |
| `ref`               | `Ref<HTMLInputElement>`                                                                                                                                                                                                                                                                                  | —                          | Input element reference                                                                                                                                      |

Native input attributes and `aria-*` target the input; `className` / `style` target the wrapper. See [PopupOptions](https://ifhover.github.io/leaf-ui/en/api/popup-options.md) for shared popup configuration.

### DateRange

A complete date range uses `readonly [Date, Date]`. With `allowEmpty`, use `OpenDateRange` from the root entry: `readonly [Date | null, Date | null]`. See [DatePreset](https://ifhover.github.io/leaf-ui/en/components/date-picker.md#datepreset) for preset entries.

| Property | Type   | Default  | Description                  |
| -------- | ------ | -------- | ---------------------------- |
| `0`      | `Date` | Required | Start, no later than the end |
| `1`      | `Date` | Required | End                          |

### TimeRangePickerMode API

Props for `picker="time"`; `TimeRange` is `readonly [string, string]`.

| Property            | Type                                                                                                                                                                 | Default   | Description                                                                         |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------- |
| `picker`            | `'time'`                                                                                                                                                             | Required  | Time-only range mode; pass time.                                                    |
| `value`             | `readonly [string, string] \| null`                                                                                                                                  | —         | Controlled tuple of 24-hour strings; null represents an empty range.                |
| `defaultValue`      | `readonly [string, string] \| null`                                                                                                                                  | `null`    | Initial value; uncontrolled fields support native form reset.                       |
| `onChange`          | `(value: readonly [string, string] \| null) => void`                                                                                                                 | —         | Return a tuple of 24-hour strings on commit, or null on clear.                      |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                               | `'md'`    | Presentation size.                                                                  |
| `status`            | `'error' \| 'warning'`                                                                                                                                               | —         | Show an error or warning appearance without performing validation.                  |
| `allowClear`        | `boolean`                                                                                                                                                            | `true`    | Show a clear action.                                                                |
| `inputReadOnly`     | `boolean`                                                                                                                                                            | —         | Disable typing while retaining panel selection.                                     |
| `minTime`           | `string`                                                                                                                                                             | —         | Earliest selectable time, inclusive, as HH:mm or HH:mm:ss.                          |
| `maxTime`           | `string`                                                                                                                                                             | —         | Latest selectable time, inclusive, as HH:mm or HH:mm:ss.                            |
| `disabledTime`      | `(parts: `[`TimeParts`](https://ifhover.github.io/leaf-ui/en/components/date-picker.md#timeparts)`, position: 'start' \| 'end') => boolean`                          | —         | Disable times; typing and panel selection use the same rules.                       |
| `allowOvernight`    | `boolean`                                                                                                                                                            | `false`   | Allow a time-only range to cross midnight.                                          |
| `needConfirm`       | `boolean`                                                                                                                                                            | `false`   | Require OK or Enter to commit; discard the draft on blur when enabled.              |
| `showSeconds`       | `boolean`                                                                                                                                                            | `false`   | Display and edit seconds; otherwise seconds are zero.                               |
| `use12Hours`        | `boolean`                                                                                                                                                            | `false`   | Use a 12-hour clock with AM/PM.                                                     |
| `minuteStep`        | `number`                                                                                                                                                             | `1`       | Minute segment step and column interval, retaining existing off-step values.        |
| `secondStep`        | `number`                                                                                                                                                             | `1`       | Second segment step and column interval, retaining existing off-step values.        |
| `open`              | `boolean`                                                                                                                                                            | —         | Control whether the panel is open.                                                  |
| `defaultOpen`       | `boolean`                                                                                                                                                            | —         | Initial open state.                                                                 |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                            | —         | Called when the panel opens or closes.                                              |
| `panelVariant`      | `'plain' \| 'card'`                                                                                                                                                  | `'plain'` | Panel appearance; card places the content on an inset surface above a muted canvas. |
| `popupPlacement`    | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | —         | Placement relative to the trigger.                                                  |
| `popupClassName`    | `string`                                                                                                                                                             | —         | Custom class for the popup.                                                         |
| `popupStyle`        | `CSSProperties`                                                                                                                                                      | —         | Custom popup styles.                                                                |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                      | —         | Wrap or extend popup content; retain the supplied content to preserve interaction.  |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                  | —         | Return a popup container, including a ShadowRoot.                                   |
