Date Field

An easily stylable date field component.

Date

YYYY

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

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

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

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

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

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`

The adapter also supports locale-aware meta tokens that expand to localized date 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 (numeric)

YYYY

With weekday

EEEE

MMMM

YYYY

ISO format

YYYY

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

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

export default function ExampleDateFieldCustomFormat() {
  return (
    <div className={styles.Wrapper}>
      <div className={fieldStyles.Field}>
        <label htmlFor="date-field-numeric" className={fieldStyles.Label}>
          Default (numeric)
        </label>
        <DateField.Root id="date-field-numeric" className={fieldStyles.Root}>
          {(section) => (
            <DateField.Section
              key={section.index}
              className={fieldStyles.Section}
              section={section}
            />
          )}
        </DateField.Root>
      </div>
      <div className={fieldStyles.Field}>
        <label htmlFor="date-field-weekday" className={fieldStyles.Label}>
          With weekday
        </label>
        <DateField.Root
          id="date-field-weekday"
          className={fieldStyles.Root}
          format="EEEE, MMMM dd, yyyy"
        >
          {(section) => (
            <DateField.Section
              key={section.index}
              className={fieldStyles.Section}
              section={section}
            />
          )}
        </DateField.Root>
      </div>
      <div className={fieldStyles.Field}>
        <label htmlFor="date-field-iso" className={fieldStyles.Label}>
          ISO format
        </label>
        <DateField.Root id="date-field-iso" className={fieldStyles.Root} format="yyyy-MM-dd">
          {(section) => (
            <DateField.Section
              key={section.index}
              className={fieldStyles.Section}
              section={section}
            />
          )}
        </DateField.Root>
      </div>
    </div>
  );
}

Clear button

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

Date

YYYY

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

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

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

Validation

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

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

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

export default function ExampleDateFieldValidation() {
  return (
    <Form
      className={styles.Form}
      onFormSubmit={(formData) => {
        alert(`Submitted: ${formData.date}`);
      }}
    >
      <Field.Root name="date" className={fieldStyles.Field}>
        <Field.Label className={fieldStyles.Label}>
          Date (between {format(min, 'MMM d')} and {format(max, 'MMM d, yyyy')})
        </Field.Label>
        <DateField.Root className={fieldStyles.Root} min={min} max={max}>
          {(section) => (
            <DateField.Section
              key={section.index}
              className={fieldStyles.Section}
              section={section}
            />
          )}
        </DateField.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-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 { DateField } from '@base-ui/react/date-field';
import { LocalizationProvider } from '@base-ui/react/localization-provider';
import fieldStyles from './date-field.module.css';
import styles from './index.module.css';

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

API reference

Root

Groups all parts of the date 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

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.'

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: DateField.Root.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

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

data-disabled

Present when the date field is disabled.

data-readonly

Present when the date field is readonly.

data-required

Present when the date field is required.

data-valid

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

data-invalid

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

data-dirty

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

data-touched

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

data-filled

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

data-focused

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

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

DateField.Root.PropsHide

Re-Export of Root props as DateFieldRootProps

DateField.Root.StateHide

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

DateField.Root.ActionsHide

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

styleReact.CSSProperties | function—

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

DateField.Section.PropsHide

Re-Export of Section props as DateFieldSectionProps

DateField.Section.StateHide

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

DateField.SectionList.PropsHide

Re-Export of SectionList props as DateFieldSectionListProps

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

styleReact.CSSProperties | function—

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

DateField.Clear.PropsHide

Re-Export of Clear props as DateFieldClearProps

DateField.Clear.StateHide

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

Usage guidelines

Anatomy

Examples

Custom format

Clear button

Validation

Localization

API reference

Root

DateField.Root.PropsHide

DateField.Root.StateHide

DateField.Root.ActionsHide

Section

DateField.Section.PropsHide

DateField.Section.StateHide

SectionList

DateField.SectionList.PropsHide

Clear

DateField.Clear.PropsHide

DateField.Clear.StateHide