Time Field

An easily stylable time field component.

Time

index.tsx time-field.module.css theme.css

'use client';
import * as React from 'react';
import { TimeField } from '@base-ui/react/time-field';
import styles from './time-field.module.css';

export default function ExampleTimeField() {
  const id = React.useId();
  return (
    <div className={styles.Field}>
      <label htmlFor={id} className={styles.Label}>
        Time
      </label>
      <TimeField.Root id={id} className={styles.Root}>
        {(section) => (
          <TimeField.Section key={section.index} className={styles.Section} section={section} />
        )}
      </TimeField.Root>
    </div>
  );
}

Usage guidelines

Form controls must have an accessible name: It can be created using a <label> element or the Field component. See the forms guide.

Anatomy

Import the component and assemble its parts:

Anatomy

import { TimeField } from '@base-ui/react/time-field';

<TimeField.Root>
  <TimeField.SectionList>
    <TimeField.Section />
  </TimeField.SectionList>
  <TimeField.Clear />
</TimeField.Root>

Use the format prop to customize the time display format. The format string uses tokens from the configured date adapter (date-fns by default). The supported section types are hours, minutes, seconds, and meridiem.

When using the date-fns adapter, common tokens include:

Section	Tokens	Example
Hours (24h)	`H`, `HH`	`9`, `09`
Hours (12h)	`h`, `hh`	`9`, `09`
Minutes	`m`, `mm`	`5`, `05`
Seconds	`s`, `ss`	`8`, `08`
Meridiem	`a`, `aa`, `aaa`	`AM`

The adapter also supports locale-aware meta tokens that expand to localized time patterns: p (short), pp (medium), ppp (long), and pppp (full).

See the date-fns format reference for the full token list. Not all date-fns tokens are supported — only those that map to the section types listed above.

Default format

12-hour with seconds

24-hour with seconds

index.tsx time-field.module.css index.module.css theme.css

'use client';
import * as React from 'react';
import { TimeField } from '@base-ui/react/time-field';
import fieldStyles from './time-field.module.css';
import styles from './index.module.css';

export default function ExampleTimeFieldCustomFormat() {
  return (
    <div className={styles.Wrapper}>
      <div className={fieldStyles.Field}>
        <label htmlFor="default-format" className={fieldStyles.Label}>
          Default format
        </label>
        <TimeField.Root id="default-format" className={fieldStyles.Root}>
          {(section) => (
            <TimeField.Section
              key={section.index}
              className={fieldStyles.Section}
              section={section}
            />
          )}
        </TimeField.Root>
      </div>
      <div className={fieldStyles.Field}>
        <label htmlFor="12-hour-seconds" className={fieldStyles.Label}>
          12-hour with seconds
        </label>
        <TimeField.Root id="12-hour-seconds" className={fieldStyles.Root} format="hh:mm:ss aa">
          {(section) => (
            <TimeField.Section
              key={section.index}
              className={fieldStyles.Section}
              section={section}
            />
          )}
        </TimeField.Root>
      </div>
      <div className={fieldStyles.Field}>
        <label htmlFor="24-hour-seconds" className={fieldStyles.Label}>
          24-hour with seconds
        </label>
        <TimeField.Root id="24-hour-seconds" className={fieldStyles.Root} format="HH:mm:ss">
          {(section) => (
            <TimeField.Section
              key={section.index}
              className={fieldStyles.Section}
              section={section}
            />
          )}
        </TimeField.Root>
      </div>
    </div>
  );
}

Clear button

Wrap the sections in <TimeField.SectionList> to render the clear button next to them using <TimeField.Clear>. The SectionList groups all sections into a single element so that additional controls can be placed alongside them inside the field.

Time

index.tsx time-field.module.css theme.css

'use client';
import * as React from 'react';
import { TimeField } from '@base-ui/react/time-field';
import styles from './time-field.module.css';

export default function ExampleTimeFieldClearButton() {
  const id = React.useId();
  return (
    <div className={styles.Field}>
      <label htmlFor={id} className={styles.Label}>
        Time
      </label>
      <TimeField.Root id={id} className={styles.Root}>
        <TimeField.SectionList>
          {(section) => (
            <TimeField.Section key={section.index} className={styles.Section} section={section} />
          )}
        </TimeField.SectionList>
        <TimeField.Clear className={styles.Clear}>{'\u2715'}</TimeField.Clear>
      </TimeField.Root>
    </div>
  );
}

Validation

Use the min and max props to constrain the allowed time range. Combine with <Field.Error> to display validation messages.

index.tsx time-field.module.css index.module.css theme.css

'use client';
import * as React from 'react';
import { format } from 'date-fns/format';
import { Field } from '@base-ui/react/field';
import { Form } from '@base-ui/react/form';
import { TimeField } from '@base-ui/react/time-field';
import fieldStyles from './time-field.module.css';
import styles from './index.module.css';

const min = new Date(2026, 0, 1, 9, 0, 0);
const max = new Date(2026, 0, 1, 17, 30, 0);

export default function ExampleTimeFieldValidation() {
  return (
    <Form
      className={styles.Form}
      onFormSubmit={(formData) => {
        alert(`Submitted: ${formData.time}`);
      }}
    >
      <Field.Root name="time" className={fieldStyles.Field}>
        <Field.Label className={fieldStyles.Label}>
          Time (between {format(min, 'h:mm a')} and {format(max, 'h:mm a')})
        </Field.Label>
        <TimeField.Root className={fieldStyles.Root} min={min} max={max}>
          {(section) => (
            <TimeField.Section
              key={section.index}
              className={fieldStyles.Section}
              section={section}
            />
          )}
        </TimeField.Root>
        <Field.Error match="rangeUnderflow" className={styles.Error}>
          Time must be on or after {format(min, 'h:mm a')}
        </Field.Error>
        <Field.Error match="rangeOverflow" className={styles.Error}>
          Time must be on or before {format(max, 'h:mm a')}
        </Field.Error>
      </Field.Root>
      <button type="submit" className={styles.Button}>
        Submit
      </button>
    </Form>
  );
}

Localization

Use <LocalizationProvider> to set the locale and customize placeholder text via the translations prop.

French locale (24h clock by default)

Custom placeholders

index.tsx time-field.module.css index.module.css theme.css

'use client';
import * as React from 'react';
import { fr } from 'date-fns/locale/fr';
import { TimeField } from '@base-ui/react/time-field';
import { LocalizationProvider } from '@base-ui/react/localization-provider';
import fieldStyles from './time-field.module.css';
import styles from './index.module.css';

export default function ExampleTimeFieldLocalization() {
  return (
    <div className={styles.Wrapper}>
      <LocalizationProvider temporalLocale={fr}>
        <div className={fieldStyles.Field}>
          <label htmlFor="french-locale" className={fieldStyles.Label}>
            French locale (24h clock by default)
          </label>
          <TimeField.Root id="french-locale" className={fieldStyles.Root}>
            {(section) => (
              <TimeField.Section
                key={section.index}
                className={fieldStyles.Section}
                section={section}
              />
            )}
          </TimeField.Root>
        </div>
      </LocalizationProvider>
      <LocalizationProvider
        translations={{
          temporalFieldHoursPlaceholder: () => 'hh',
          temporalFieldMinutesPlaceholder: () => 'mm',
          temporalFieldMeridiemPlaceholder: () => 'AM',
        }}
      >
        <div className={fieldStyles.Field}>
          <label htmlFor="custom-placeholders" className={fieldStyles.Label}>
            Custom placeholders
          </label>
          <TimeField.Root id="custom-placeholders" className={fieldStyles.Root} ampm>
            {(section) => (
              <TimeField.Section
                key={section.index}
                className={fieldStyles.Section}
                section={section}
              />
            )}
          </TimeField.Root>
        </div>
      </LocalizationProvider>
    </div>
  );
}

API reference

Root

Groups all parts of the time field. Renders a <div> element and a hidden <input> beside.

namestring—

Name: name
Description: Identifies the field when a form is submitted.
Type: string | undefined

defaultValueTemporalValue—

Name: defaultValue
Description: The uncontrolled value that should be initially selected. To render a controlled temporal field, use the value prop instead.
Type: TemporalValue | undefined

valueTemporalValue—

Name: value
Description: The controlled value that should be selected. To render an uncontrolled temporal field, use the defaultValue prop instead.
Type: TemporalValue | undefined

onValueChangefunction—

Name: onValueChange
Description: Event handler called when the selected value changes. Provides the new value as an argument.
Type: | (( value: TemporalValue, eventDetails: TemporalFieldValueChangeEventDetails, ) => void) | undefined

actionsRefReact.RefObject<TemporalFieldRootActions | null>—

Name: actionsRef
Description: A ref to imperative actions.

clear: Clears the field value.
Type: | React.RefObject<TemporalFieldRootActions | null> | undefined

ampmbooleanbased on the current locale

Name: ampm
Description: Whether to use 12-hour format with AM/PM or 24-hour format. Is ignored if a custom format is provided.
Type: boolean | undefined
Default: based on the current locale

referenceDateDate'The closest valid date using the validation props.'

Name: referenceDate
Description: The date used to generate the new value when both value and defaultValue are empty.
Type: Date | undefined
Default: 'The closest valid date using the validation props.'

timezonestring'The timezone of the "value" or "defaultValue" prop if defined, "default" otherwise.'

Name: timezone
Description: Choose which timezone to use for the value. Example: “default”, “system”, “UTC”, “America/New_York”. If you pass values from other timezones to some props, they will be converted to this timezone before being used.
Type: string | undefined
Default: 'The timezone of the "value" or "defaultValue" prop if defined, "default" otherwise.'

stepnumber1

Name: step
Description: The step increment for the most granular section of the field. For example, with format ‘HH:mm’ and step=5, pressing ArrowUp on the minutes section will increment by 5 (for example, 10 -> 15 -> 20).
Type: number | undefined
Default: 1

minDate—

Name: min
Description: Minimal selectable date.
Type: Date | undefined

maxDate—

Name: max
Description: Maximal selectable date.
Type: Date | undefined

formatstring—

Name: format
Description: Format of the value when rendered in the field. Only tokens that map to the supported section types (year, month, day, weekday, hours, minutes, seconds, meridiem) are recognized — other tokens are treated as literal text.
Type: string | undefined

disabledbooleanfalse

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | undefined
Default: false

readOnlybooleanfalse

Name: readOnly
Description: Whether the user should be unable to change the field value.
Type: boolean | undefined
Default: false

requiredbooleanfalse

Name: required
Description: Whether the user must enter a value before submitting a form.
Type: boolean | undefined
Default: false

inputRefReact.Ref<HTMLInputElement>—

Name: inputRef
Description: A ref to access the hidden input element.
Type: React.Ref<HTMLInputElement> | undefined

children

| React.ReactNode 
|  ((section: TemporalFieldSection, index: number) => React.ReactNode)

—

Name: children
Description: The children of the component. If a function is provided, it will be called with each section and must render a DateField.Section (or the corresponding TimeField.Section / DateTimeField.Section) for each one. Custom wrapper elements may be added around the sections.
Type: | React.ReactNode | (( section: TemporalFieldSection, index: number, ) => React.ReactNode) | undefined

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: TimeField.Root.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: TimeField.Root.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: TimeField.Root.State, ) => ReactElement) | undefined

data-disabled

Present when the time field is disabled.

data-readonly

Present when the time field is readonly.

data-required

Present when the time field is required.

data-valid

Present when the time field is in valid state (when wrapped in Field.Root).

data-invalid

Present when the time field is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the time field’s value has changed (when wrapped in Field.Root).

data-touched

Present when the time field has been touched (when wrapped in Field.Root).

data-filled

Present when the time field is filled (when wrapped in Field.Root).

data-focused

Present when the time field is focused (when wrapped in Field.Root).

Attribute	Description	-
`data-disabled`	Present when the time field is disabled.
`data-readonly`	Present when the time field is readonly.
`data-required`	Present when the time field is required.
`data-valid`	Present when the time field is in valid state (when wrapped in Field.Root).
`data-invalid`	Present when the time field is in invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the time field’s value has changed (when wrapped in Field.Root).
`data-touched`	Present when the time field has been touched (when wrapped in Field.Root).
`data-filled`	Present when the time field is filled (when wrapped in Field.Root).
`data-focused`	Present when the time field is focused (when wrapped in Field.Root).

TimeField.Root.PropsHide

Re-Export of Root props as TimeFieldRootProps

TimeField.Root.StateHide

type TimeFieldRootState = {
  /** Whether the user must enter a value before submitting a form. */
  required: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the user should be unable to change the field value. */
  readOnly: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
}

TimeField.Root.ActionsHide

type TimeFieldRootActions = {
  /**
   * Clears the field value.
   * If the value is already empty, it clears the sections (visual placeholders).
   */
  clear: () => void;
}

Section

Renders the content of a temporal field’s section. Renders a <div> element.

section^*

TemporalFieldSection

—

Name: section
Description: The section to render.
Type: TemporalFieldSection

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: TimeField.Section.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: TimeField.Section.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: TimeField.Section.State, ) => ReactElement) | undefined

data-empty

Present when the section value is empty.

data-section-index

Index of the section in the field.

data-separator

Present when the section is a separator (for example, “/", “-").

Attribute	Description	-
`data-empty`	Present when the section value is empty.
`data-section-index`	Index of the section in the field.
`data-separator`	Present when the section is a separator (for example, “/", “-").

TimeField.Section.PropsHide

Re-Export of Section props as TimeFieldSectionProps

TimeField.Section.StateHide

type TimeFieldSectionState = {
  /** Index of the section in the field. */
  sectionIndex: number;
  /** Whether the section is empty. */
  empty: boolean;
  /** Whether the section is a separator (for example, "/", "-"). */
  separator: boolean;
}

SectionList

Renders all sections of a temporal field. Doesn’t render its own HTML element.

children^*

(
  section: TemporalFieldSection,
  index: number,
) => React.ReactNode

—

Name: children
Description: A function that receives each section and must render a DateField.Section (or the corresponding field-type alias) for it.
Type: ( section: TemporalFieldSection, index: number, ) => React.ReactNode

TimeField.SectionList.PropsHide

Re-Export of SectionList props as TimeFieldSectionListProps

Clear

Clears the field value when clicked. Renders a <button> element.

nativeButtonbooleantrue

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).
Type: boolean | undefined
Default: true

disabledbooleanfalse

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | undefined
Default: false

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: TimeField.Clear.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: TimeField.Clear.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: TimeField.Clear.State, ) => ReactElement) | undefined

data-disabled

Present when the button is disabled.

data-readonly

Present when the field is read-only.

data-empty

Present when the field value is empty (all sections are empty).

Attribute	Description	-
`data-disabled`	Present when the button is disabled.
`data-readonly`	Present when the field is read-only.
`data-empty`	Present when the field value is empty (all sections are empty).

TimeField.Clear.PropsHide

Re-Export of Clear props as TimeFieldClearProps

TimeField.Clear.StateHide

type TimeFieldClearState = {
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field value is empty (all sections are empty). */
  empty: boolean;
  /** Whether the field is read-only. */
  readOnly: boolean;
}

Time Field

Usage guidelines

Anatomy

Examples

Custom format

Clear button

Validation

Localization

API reference

Root

TimeField.Root.PropsHide

TimeField.Root.StateHide

TimeField.Root.ActionsHide

Section

TimeField.Section.PropsHide

TimeField.Section.StateHide

SectionList

TimeField.SectionList.PropsHide

Clear

TimeField.Clear.PropsHide

TimeField.Clear.StateHide