Date Time Field

An easily stylable date time field component.

Date and time

YYYY

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

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

export default function ExampleDateTimeField() {
  const id = React.useId();
  return (
    <div className={styles.Field}>
      <label htmlFor={id} className={styles.Label}>
        Date and time
      </label>
      <DateTimeField.Root id={id} className={styles.Root}>
        {(section) => (
          <DateTimeField.Section key={section.index} className={styles.Section} section={section} />
        )}
      </DateTimeField.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 { DateTimeField } from '@base-ui/react/date-time-field';

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

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

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

Section	Tokens	Example
Year	`y`, `yy`, `yyyy`	`2024`, `24`, `2024`
Month	`M`, `MM`, `MMM`, `MMMM`	`1`, `01`, `Jan`, `January`
Day	`d`, `dd`, `do`	`5`, `05`, `5th`
Weekday	`E`, `EEE`, `EEEE`	`T`, `Tue`, `Tuesday`
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: P through PPPP for dates, p through pppp for times, and combined forms like Pp for date and time together.

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

YYYY

ISO-like format

YYYY

12-hour with meridiem

YYYY

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

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

export default function ExampleDateTimeFieldCustomFormat() {
  return (
    <div className={styles.Wrapper}>
      <div className={fieldStyles.Field}>
        <label htmlFor="default-format" className={fieldStyles.Label}>
          Default format
        </label>
        <DateTimeField.Root id="default-format" className={fieldStyles.Root}>
          {(section) => (
            <DateTimeField.Section
              key={section.index}
              className={fieldStyles.Section}
              section={section}
            />
          )}
        </DateTimeField.Root>
      </div>
      <div className={fieldStyles.Field}>
        <label htmlFor="iso-format" className={fieldStyles.Label}>
          ISO-like format
        </label>
        <DateTimeField.Root id="iso-format" className={fieldStyles.Root} format="yyyy-MM-dd HH:mm">
          {(section) => (
            <DateTimeField.Section
              key={section.index}
              className={fieldStyles.Section}
              section={section}
            />
          )}
        </DateTimeField.Root>
      </div>
      <div className={fieldStyles.Field}>
        <label htmlFor="12-hour-format" className={fieldStyles.Label}>
          12-hour with meridiem
        </label>
        <DateTimeField.Root
          id="12-hour-format"
          className={fieldStyles.Root}
          format="MM/dd/yyyy hh:mm aa"
        >
          {(section) => (
            <DateTimeField.Section
              key={section.index}
              className={fieldStyles.Section}
              section={section}
            />
          )}
        </DateTimeField.Root>
      </div>
    </div>
  );
}

Clear button

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

Date and time

YYYY

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

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

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

Validation

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

index.tsx date-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 { DateTimeField } from '@base-ui/react/date-time-field';
import fieldStyles from './date-time-field.module.css';
import styles from './index.module.css';

const min = new Date(2026, 2, 10);
const max = new Date(2026, 2, 24);

export default function ExampleDateTimeFieldValidation() {
  return (
    <Form
      className={styles.Form}
      onFormSubmit={(formData) => {
        alert(`Submitted: ${formData.datetime}`);
      }}
    >
      <Field.Root name="datetime" className={fieldStyles.Field}>
        <Field.Label className={fieldStyles.Label}>
          Date and time (between {format(min, 'MMM d')} and {format(max, 'MMM d, yyyy')})
        </Field.Label>
        <DateTimeField.Root className={fieldStyles.Root} min={min} max={max}>
          {(section) => (
            <DateTimeField.Section
              key={section.index}
              className={fieldStyles.Section}
              section={section}
            />
          )}
        </DateTimeField.Root>
        <Field.Error match="rangeUnderflow" className={styles.Error}>
          Date must be on or after {format(min, 'MMM d, yyyy')}
        </Field.Error>
        <Field.Error match="rangeOverflow" className={styles.Error}>
          Date must be on or before {format(max, 'MMM d, yyyy')}
        </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

AAAA

German locale

JJJJ

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

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

export default function ExampleDateTimeFieldLocalization() {
  return (
    <div className={styles.Wrapper}>
      <LocalizationProvider
        temporalLocale={fr}
        translations={{
          temporalFieldYearPlaceholder: ({ digitAmount }) => 'A'.repeat(digitAmount),
          temporalFieldDayPlaceholder: () => 'JJ',
        }}
      >
        <div className={fieldStyles.Field}>
          <label htmlFor="french-locale" className={fieldStyles.Label}>
            French locale
          </label>
          <DateTimeField.Root id="french-locale" className={fieldStyles.Root}>
            {(section) => (
              <DateTimeField.Section
                key={section.index}
                className={fieldStyles.Section}
                section={section}
              />
            )}
          </DateTimeField.Root>
        </div>
      </LocalizationProvider>
      <LocalizationProvider
        temporalLocale={de}
        translations={{
          temporalFieldYearPlaceholder: ({ digitAmount }) => 'J'.repeat(digitAmount),
          temporalFieldDayPlaceholder: () => 'TT',
        }}
      >
        <div className={fieldStyles.Field}>
          <label htmlFor="german-locale" className={fieldStyles.Label}>
            German locale
          </label>
          <DateTimeField.Root id="german-locale" className={fieldStyles.Root}>
            {(section) => (
              <DateTimeField.Section
                key={section.index}
                className={fieldStyles.Section}
                section={section}
              />
            )}
          </DateTimeField.Root>
        </div>
      </LocalizationProvider>
    </div>
  );
}

API reference

Root

Groups all parts of the date-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: DateTimeField.Root.State, ) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: DateTimeField.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: DateTimeField.Root.State, ) => ReactElement) | undefined

data-disabled

Present when the date-time field is disabled.

data-readonly

Present when the date-time field is readonly.

data-required

Present when the date-time field is required.

data-valid

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

data-invalid

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

data-dirty

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

data-touched

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

data-filled

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

data-focused

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

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

DateTimeField.Root.PropsHide

Re-Export of Root props as DateTimeFieldRootProps

DateTimeField.Root.StateHide

type DateTimeFieldRootState = {
  /** 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;
}

DateTimeField.Root.ActionsHide

type DateTimeFieldRootActions = {
  /**
   * 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: DateTimeField.Section.State, ) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: DateTimeField.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: DateTimeField.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, “/", “-").

DateTimeField.Section.PropsHide

Re-Export of Section props as DateTimeFieldSectionProps

DateTimeField.Section.StateHide

type DateTimeFieldSectionState = {
  /** 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

DateTimeField.SectionList.PropsHide

Re-Export of SectionList props as DateTimeFieldSectionListProps

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: DateTimeField.Clear.State, ) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: DateTimeField.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: DateTimeField.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).

DateTimeField.Clear.PropsHide

Re-Export of Clear props as DateTimeFieldClearProps

DateTimeField.Clear.StateHide

type DateTimeFieldClearState = {
  /** 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;
}

Date Time Field

Usage guidelines

Anatomy

Examples

Custom format

Clear button

Validation

Localization

API reference

Root

DateTimeField.Root.PropsHide

DateTimeField.Root.StateHide

DateTimeField.Root.ActionsHide

Section

DateTimeField.Section.PropsHide

DateTimeField.Section.StateHide

SectionList

DateTimeField.SectionList.PropsHide

Clear

DateTimeField.Clear.PropsHide

DateTimeField.Clear.StateHide