> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/time-picker.html

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

# TimePicker

Choose a time.

## Examples

Values use 24-hour HH:mm, or HH:mm:ss with showSeconds. use12Hours changes the display to a 12-hour clock with AM/PM, while values remain 24-hour. Midnight is 12 AM and noon is 12 PM. The initial draft is 09:00. Close without confirming to discard edits. Minute and second steps preserve an existing value outside the step.


Choose a time

Default time

Disabled time

basic.tsx

Copy code

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

export function TimePickerBasic() {
  return (
    <Form layout="vertical">
      <FormField label="Choose a time">
        <TimePicker aria-label="Choose a time" />
      </FormField>
      <FormField label="Default time">
        <TimePicker aria-label="Default time" defaultValue="09:30" />
      </FormField>
      <FormField label="Disabled time">
        <TimePicker aria-label="Disabled time" defaultValue="18:00" disabled />
      </FormField>
    </Form>
  );
}
```

Expand code


Meeting time

15-minute steps. Current:14:30

Preserved time

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/time-picker/controlled.tsx"
import { Form, FormField, Text, TimePicker } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function TimePickerControlled() {
  const [time, setTime] = useState<string | null>('14:30');
  return (
    <Form layout="vertical">
      <FormField label="Meeting time">
        <TimePicker aria-label="Meeting time" value={time} onChange={setTime} minuteStep={15} />
      </FormField>
      <Text tone="muted">15-minute steps. Current:{time || 'Not selected'}</Text>
      <FormField label="Preserved time">
        <TimePicker
          aria-label="Preserved time"
          defaultValue="08:07"
          minuteStep={15}
          allowClear={false}
        />
      </FormField>
    </Form>
  );
}
```

Expand code


12-hour clock

Include seconds

twelve-hours.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/time-picker/twelve-hours.tsx"
import { Form, FormField, TimePicker } from '@ifhover/leaf-ui';

export function TimePickerTwelveHours() {
  return (
    <Form layout="vertical">
      <FormField label="12-hour clock">
        <TimePicker aria-label="12-hour clock" use12Hours defaultValue="14:30" />
      </FormField>
      <FormField label="Include seconds">
        <TimePicker
          aria-label="Include seconds"
          use12Hours
          showSeconds
          secondStep={10}
          defaultValue="00:05:30"
        />
      </FormField>
    </Form>
  );
}
```

Expand code

## Disabled times


Business hours; disabled choices cannot be submitted

capabilities.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/time-picker/capabilities.tsx"
import { Flex, Space, TimePicker } from '@ifhover/leaf-ui';

export function Capabilities() {
  return (
    <Space direction="vertical" align="stretch">
      <Flex direction="column" gap="sm" align="center">
        {'Business hours; disabled choices cannot be submitted'}
        <TimePicker
          use12Hours
          defaultValue="09:30"
          disabledTime={(time) => time.hour < 9 || time.hour >= 18}
          minuteStep={15}
        />
      </Flex>
    </Space>
  );
}
```

Expand code

## TimePicker API

| Property            | Type                                                                                                                                                                 | Default | Description                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| `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.                                  |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                               | `'md'`  | Control size                                                                       |
| `status`            | `'error' \| 'warning'`                                                                                                                                               | —       | Validation appearance                                                              |
| `allowClear`        | `boolean`                                                                                                                                                            | `true`  | Show a clear button                                                                |
| `inputReadOnly`     | `boolean`                                                                                                                                                            | —       | Disable typing while retaining panel selection.                                    |
| `open`              | `boolean`                                                                                                                                                            | —       | Control whether the panel is open.                                                 |
| `defaultOpen`       | `boolean`                                                                                                                                                            | —       | Initial open state.                                                                |
| `value`             | `string \| null`                                                                                                                                                     | `null`  | Controlled / initial HH:mm value; HH:mm:ss when seconds are enabled                |
| `defaultValue`      | `string \| null`                                                                                                                                                     | `null`  | Controlled / initial HH:mm value; HH:mm:ss when seconds are enabled                |
| `minuteStep`        | `number`                                                                                                                                                             | `5`     | Minute step, an integer from 1 to 60                                               |
| `secondStep`        | `number`                                                                                                                                                             | `1`     | Second step, an integer from 1 to 60                                               |
| `showSeconds`       | `boolean`                                                                                                                                                            | `false` | Show seconds and use HH:mm:ss values                                               |
| `use12Hours`        | `boolean`                                                                                                                                                            | `false` | Display a 12-hour clock with AM/PM                                                 |
| `onChange`          | `(value: string \| null) => void`                                                                                                                                    | —       | Confirmed time; null when cleared                                                  |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                            | —       | Panel open-state changes                                                           |
| `disabledTime`      | `(parts: `[`TimeParts`](#timeparts)`) => boolean`                                                                                                                    | —       | Disable times; typing and panel selection use the same rules.                      |
| `disabled`          | `boolean`                                                                                                                                                            | `false` | Disable interaction.                                                               |
| `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.                        |
| `ref`               | `Ref<HTMLInputElement>`                                                                                                                                              | —       | DOM reference                                                                      |

## Types

Import TimePickerProps to describe component props. Option types in the API table link to their detailed fields above.

```ts
import type { TimePickerProps } from '@ifhover/leaf-ui';
```

## Forms and localization

Use name to include values in FormData. Uncontrolled fields follow form reset; reset controlled values in application state. Place controls in [FormField](https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/form.md#formfield-api) for labels, help and errors. [ConfigProvider](https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/config-provider.md) supplies regional themes and translated built-in UI. Application labels and options are your responsibility.

Type `HH:mm` or `HH:mm:ss`; 12-hour text accepts AM/PM or 上午/下午. Press Enter to submit, or adjust columns and click OK. Every mode requires confirmation. Now updates the draft and still requires OK. Escape or leaving the field discards changes. Other input attributes and aria-\* target the input; className/style target the wrapper. ArrowDown moves focus to the selected hour.

## TimeParts

| Property | Type     | Default | Description                 |
| -------- | -------- | ------- | --------------------------- |
| `hour`   | `number` | —       | Required. Configure hour.   |
| `minute` | `number` | —       | Required. Configure minute. |
| `second` | `number` | —       | Required. Configure second. |