# TimeField · HeroUI

> Time input field with labels, descriptions, and validation built on React Aria TimeField

- Page: https://jiguang132.com/systems/heroui/docs/components/time-field
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## Import

```tsx
import { TimeField } from '@heroui/react';
```

### Usage


> Example `time-field-basic`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


### Anatomy

```tsx
import {TimeField, Label, Description, FieldError} from '@heroui/react';

export default () => (
  <TimeField>
    <Label />
    <TimeField.Group>
      <TimeField.Input>
        {(segment) => <TimeField.Segment segment={segment} />}
      </TimeField.Input>
    </TimeField.Group>
    <Description />
    <FieldError />
  </TimeField>
)
```

> **TimeField** combines label, time input, description, and error into a single accessible component.

### With Description


> Example `time-field-with-description`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


### Required Field


> Example `time-field-required`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


### Validation

Use `isInvalid` together with `FieldError` to surface validation messages.


> Example `time-field-invalid`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


### With Validation

TimeField supports validation with `minValue`, `maxValue`, and custom validation logic.


> Example `time-field-with-validation`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


### Controlled

Control the value to synchronize with other components or state management.


> Example `time-field-controlled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


### Disabled State


> Example `time-field-disabled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


### With Icons

Add prefix or suffix icons to enhance the time field.


> Example `time-field-with-prefix-icon`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


> Example `time-field-with-suffix-icon`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


> Example `time-field-with-prefix-and-suffix`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


### Full Width


> Example `time-field-full-width`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


### On Surface

When used inside a [Surface](/systems/heroui/docs/components/surface) component, use `variant="secondary"` on TimeField.Group to apply the lower emphasis variant suitable for surface backgrounds.


> Example `time-field-on-surface`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


### Form Example

Complete form example with validation and submission handling.


> Example `time-field-form-example`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


### Custom Render Function


> Example `time-field-custom-render-function`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/time-field


## Styling

### Passing Tailwind CSS classes

```tsx
import {TimeField, Label, Description} from '@heroui/react';

function CustomTimeField() {
  return (
    <TimeField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
      <Label className="text-sm font-semibold text-default-700">
        Appointment time
      </Label>
      <TimeField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
        <TimeField.Input>
          {(segment) => <TimeField.Segment segment={segment} />}
        </TimeField.Input>
      </TimeField.Group>
      <Description className="text-xs text-default-500">
        Select a time for your appointment.
      </Description>
    </TimeField>
  );
}
```

### Customizing the component classes

TimeField has minimal default styling. Override the `.time-field` class to customize the container styling.

```css
@layer components {
  .time-field {
    @apply flex flex-col gap-1;

    &[data-invalid="true"],
    &[aria-invalid="true"] {
      [data-slot="description"] {
        @apply hidden;
      }
    }

    [data-slot="label"] {
      @apply w-fit;
    }

    [data-slot="description"] {
      @apply px-1;
    }
  }
}
```

### CSS Classes

- `.time-field` – Root container with minimal styling (`flex flex-col gap-1`)

> **Note:** Child components ([Label](/systems/heroui/docs/components/label), [Description](/systems/heroui/docs/components/description), [FieldError](/systems/heroui/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options. TimeField.Group styling is documented below in the API Reference section.

### Interactive States

TimeField automatically manages these data attributes based on its state:

- **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
- **Required**: `[data-required="true"]` - Applied when `isRequired` is true
- **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
- **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused

## API Reference

### TimeField Props

TimeField inherits all props from React Aria's [TimeField](https://react-aria.adobe.com/TimeField) component.

#### Base Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode \| (values: TimeFieldRenderProps) => React.ReactNode` | - | Child components (Label, TimeField.Group, etc.) or render function. |
| `className` | `string \| (values: TimeFieldRenderProps) => string` | - | CSS classes for styling, supports render props. |
| `style` | `React.CSSProperties \| (values: TimeFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. |
| `fullWidth` | `boolean` | `false` | Whether the time field should take full width of its container |
| `id` | `string` | - | The element's unique identifier. |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TimeFieldRenderProps>` | - | Overrides the default DOM element with a custom render function.|

#### Value Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `TimeValue \| null` | - | Current value (controlled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
| `defaultValue` | `TimeValue \| null` | - | Default value (uncontrolled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
| `onChange` | `(value: TimeValue \| null) => void` | - | Handler called when the value changes. |
| `placeholderValue` | `TimeValue \| null` | - | Placeholder time that influences the format of the placeholder. Defaults to 12:00 AM or 00:00 depending on the hour cycle. |

#### Validation Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `isRequired` | `boolean` | `false` | Whether user input is required before form submission. |
| `isInvalid` | `boolean` | - | Whether the value is invalid. |
| `minValue` | `TimeValue \| null` | - | The minimum allowed time that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
| `maxValue` | `TimeValue \| null` | - | The maximum allowed time that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
| `validate` | `(value: TimeValue) => ValidationError \| true \| null \| undefined` | - | Custom validation function. |
| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. |

#### Format Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `granularity` | `'hour' \| 'minute' \| 'second'` | `'minute'` | Determines the smallest unit displayed in the time picker. |
| `hourCycle` | `12 \| 24` | - | Whether to display time in 12 or 24 hour format. By default, determined by locale. |
| `hideTimeZone` | `boolean` | `false` | Whether to hide the time zone abbreviation. |
| `shouldForceLeadingZeros` | `boolean` | - | Whether to always show leading zeros in the hour field. By default, determined by locale. |

#### State Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed. |

#### Form Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | - | Name of the input element, for HTML form submission. Submits as ISO 8601 string. |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |

#### Accessibility Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `aria-label` | `string` | - | Accessibility label when no visible label is present. |
| `aria-labelledby` | `string` | - | ID of elements that label this field. |
| `aria-describedby` | `string` | - | ID of elements that describe this field. |
| `aria-details` | `string` | - | ID of elements with additional details. |

### Composition Components

TimeField works with these separate components that should be imported and used directly:

- **Label** - Field label component from `@heroui/react`
- **TimeField.Group** - Time input group component (documented below)
- **TimeField.Input** - Input component with segmented editing from `@heroui/react`
- **TimeField.Segment** - Individual time segment (hour, minute, second, etc.)
- **TimeField.Prefix** / **TimeField.Suffix** - Prefix and suffix slots for the input group
- **Description** - Helper text component from `@heroui/react`
- **FieldError** - Validation error message from `@heroui/react`

Each of these components has its own props API. Use them directly within TimeField for composition:

```tsx
import {parseTime} from '@internationalized/date';
import {TimeField, Label, Description, FieldError} from '@heroui/react';

<TimeField
  isRequired
  isInvalid={hasError}
  minValue={parseTime('09:00')}
  maxValue={parseTime('17:00')}
  value={time}
  onChange={setTime}
>
  <Label>Appointment Time</Label>
  <TimeField.Group>
    <TimeField.Input>
      {(segment) => <TimeField.Segment segment={segment} />}
    </TimeField.Input>
  </TimeField.Group>
  <Description>Select a time between 9:00 AM and 5:00 PM.</Description>
  <FieldError>Please select a valid time.</FieldError>
</TimeField>
```

### TimeValue Types

TimeField uses types from [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/):

- `Time` - Time only (hour, minute, second)
- `CalendarDateTime` - Date with time but no timezone (TimeField displays only the time portion)
- `ZonedDateTime` - Date with time and timezone (TimeField displays only the time portion)

Example:

```tsx
import {parseTime, Time, getLocalTimeZone, now} from '@internationalized/date';

// Parse from string
const time = parseTime('14:30');

// Create from current time
const currentTime = now(getLocalTimeZone());
const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second);

// Use in TimeField
<TimeField value={time} onChange={setTime}>
  {/* ... */}
</TimeField>
```

> **Note:** TimeField uses the [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) package for time manipulation, parsing, and type definitions. See the [Internationalized Date documentation](https://react-aria.adobe.com/internationalized/date/) for more information about available types and functions.

### TimeFieldRenderProps

When using render props with `className`, `style`, or `children`, these values are available:

| Prop | Type | Description |
|------|------|-------------|
| `isDisabled` | `boolean` | Whether the field is disabled. |
| `isInvalid` | `boolean` | Whether the field is currently invalid. |
| `isReadOnly` | `boolean` | Whether the field is read-only. |
| `isRequired` | `boolean` | Whether the field is required. |
| `isFocused` | `boolean` | Whether the field is currently focused. |
| `isFocusWithin` | `boolean` | Whether any child element is focused. |
| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |

### TimeField.Group Props

TimeField.Group accepts all props from React Aria's `Group` component plus the following:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |

### TimeField.Input Props

TimeField.Input accepts all props from React Aria's `DateInput` component plus the following:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |

The `TimeField.Input` component accepts a render prop function that receives date segments. Each segment represents a part of the time (hour, minute, second, etc.).

### TimeField.Segment Props

TimeField.Segment accepts all props from React Aria's `DateSegment` component:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `segment` | `DateSegment` | - | The date segment object from the TimeField.Input render prop. |
| `className` | `string` | - | Tailwind classes merged with the component styles. |

### TimeField.Prefix Props

TimeField.Prefix accepts standard HTML `div` attributes:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `children` | `ReactNode` | - | Content to display in the prefix slot. |

### TimeField.Suffix Props

TimeField.Suffix accepts standard HTML `div` attributes:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `children` | `ReactNode` | - | Content to display in the suffix slot. |

## TimeField.Group Styling

### Customizing the component classes

The base classes power every instance. Override them once with `@layer components`.

```css
@layer components {
  .date-input-group {
    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;

    &:hover,
    &[data-hovered="true"] {
      @apply bg-field-hover;
    }

    &[data-focus-within="true"],
    &:focus-within {
      @apply status-focused-field;
    }

    &[data-invalid="true"] {
      @apply status-invalid-field;
    }

    &[data-disabled="true"],
    &[aria-disabled="true"] {
      @apply status-disabled;
    }
  }

  .date-input-group__input {
    @apply flex flex-1 items-center gap-px rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
  }

  .date-input-group__segment {
    @apply inline-block rounded-md px-0.5 text-end tabular-nums outline-none;

    &:focus,
    &[data-focused="true"] {
      @apply bg-accent-soft text-accent-soft-foreground;
    }
  }

  .date-input-group__prefix,
  .date-input-group__suffix {
    @apply pointer-events-none shrink-0 text-field-placeholder flex items-center;
  }
}
```

### TimeField.Group CSS Classes

- `.date-input-group` – Root container styling
- `.date-input-group__input` – Input wrapper styling
- `.date-input-group__segment` – Individual time segment styling
- `.date-input-group__prefix` – Prefix element styling
- `.date-input-group__suffix` – Suffix element styling

### TimeField.Group Interactive States

- **Hover**: `:hover` or `[data-hovered="true"]`
- **Focus Within**: `[data-focus-within="true"]` or `:focus-within`
- **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`)
- **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]`
- **Segment Focus**: `:focus` or `[data-focused="true"]` on segment elements
- **Segment Placeholder**: `[data-placeholder="true"]` on segment elements

---

Index of all JGuang resources: https://jiguang132.com/llms.txt