Skip to main content
U.S. Flag

An official website of the United States government

Multi-Input Date Field

Date field (multi-input) provides date entry, spaced over three separate inputs for month, day, and year.

Examples

Loading

Code

React

React Properties Documentation
NameTypeDefaultDescription
autoCompleteboolean

Adds autocomplete attributes bday-day, bday-month and bday-year to the corresponding <MultiInputDateField> inputs

dateFormatter(...args: any[]) => any

Optional method to format the input field values. If this method is provided, the returned value will be passed as a second argument to the onBlur and onChange callbacks. This method receives an object as its only argument, in the shape of: { day, month, year }

By default dateFormatter will be set to the defaultDateFormatter function, which prevents days/months more than 2 digits & years more than 4 digits.

labelReact.ReactNode

The primary label, rendered above the individual month/day/year fields

labelIdstring

A unique ID to be used for the MultiInputDateField label. If one isn't provided, a unique ID will be generated.

requirementLabelReact.ReactNode

Text showing the requirement ("Required", "Optional", etc.). See Required and Optional Fields.

onBlur(...args: any[]) => any

Called anytime any date input is blurred

onComponentBlur(...args: any[]) => any

Called when any date input is blurred and the focus does not land on one of the other date inputs inside this component (i.e., when the whole component loses focus)

onChange(...args: any[]) => any

Called anytime any date input is changed

dayLabelReact.ReactNode

Label for the day field

dayNamestring

name for the day input field

dayDefaultValuestring | number

Initial value for the day input field. Use this for an uncontrolled component; otherwise, use the dayValue property.

dayFieldRef(...args: any[]) => any

Access a reference to the day input

dayInvalidboolean

Apply error styling to the day input

dayValuestring | number

Sets the day input's value. Use this in combination with onChange for a controlled component; otherwise, set dayDefaultValue.

monthLabelReact.ReactNode

Label for the month field

monthNamestring

name for the month input field

monthDefaultValuestring | number

Initial value for the month input field. Use this for an uncontrolled component; otherwise, use the monthValue property.

monthFieldRef(...args: any[]) => any

Access a reference to the month input

monthInvalidboolean

Apply error styling to the month input

monthValuestring | number

Sets the month input's value. Use this in combination with onChange for a controlled component; otherwise, set monthDefaultValue.

yearDefaultValuestring | number

Initial value for the year input field. Use this for an uncontrolled component; otherwise, use the yearValue property.

yearFieldRef(...args: any[]) => any

Access a reference to the year input

yearInvalidboolean

Apply error styling to the year input

yearLabelReact.ReactNode

Label for the year input field

yearNamestring

name for the year field

yearValuestring | number

Sets the year input's value. Use this in combination with onChange for a controlled component; otherwise, set yearDefaultValue.

Styles

The following Sass variables can be overridden to customize Input/Form components:

Sass variables for text-input
VariableDefault Core Theme Value
$text-input__line-height1.3
$text-input__background-color--disabled$color-border
$text-input__border-width2px
$text-input__border-width--error3px
$text-input__border-width--success3px
$text-input__border-color$color-base
$text-input__border-color--disabled$color-gray-light
$text-input__border-color--error$color-error
$text-input__border-color--error--inverse$color-error-light
$text-input__border-color--inverse$color-black
$text-input__border-color--success$color-green-light
$text-input__color$color-base
$text-input__padding8px
$text-input__border-radius3px

Form components

This component also makes use of form field styles, which can be customized by the following variables:

Sass variables for form
VariableDefault Core Theme Value
$form-label__color--inverse$color-white
$form__max-width460px
$form__max-width--small6em
$form__max-width--medium12em
$form-hint__color$color-gray
$form-hint__color--inverse$color-muted-inverse
$form-error__color$color-error
$form-error__color--inverse$color-error-light

Guidance

When to use

Use this date field when:

  • User flow requires inputs be separated
  • Functionality/back-end systems can't support a single date field entry

Generally used for more memorable dates like date of birth, marriage date, or income start date.

When to consider alternatives

  • Don't use this date field if either single-input or date picker are feasible. This pattern is least effective with users.

Usage

  • Allow users to enter one-digit numbers with or without the "0" prior to the number. Example: "1" as well as "01" for a month or day.

Accessibility

  • These text fields should follow the accessibility guidelines for all text inputs.
  • Do not use JavaScript to auto advance the focus from one field to the next. This makes it difficult for keyboard-only users to navigate and correct mistakes.

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

  • Color

    Meets AA color contrast standards for accessibility and color blindness.
    Complete
  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
    Complete
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
    Complete
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
    Complete
  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Complete

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete
  • Responsive

    Component designed to work in all responsive breakpoints.
    Complete
  • Spanish translations

    Includes Spanish translations for default text content.
    Complete

Tokens

  • Code

    Tokens implemented in code.
    Complete
  • Design

    Tokens implemented in the Sketch.
    Complete