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
autoCompletebooleanAdds autocomplete attributes bday-day, bday-month and bday-year to the corresponding <MultiInputDateField> inputs
dateFormatter(...args: any[]) => anyOptional 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.
labelReactNodeThe primary label, rendered above the individual month/day/year fields
labelIdstringA unique ID to be used for the MultiInputDateField label. If one isn't provided, a unique ID will be generated.
requirementLabelReactNodeText showing the requirement ("Required", "Optional", etc.). See Required and Optional Fields.
onBlur(...args: any[]) => anyCalled anytime any date input is blurred
onComponentBlur(...args: any[]) => anyCalled 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[]) => anyCalled anytime any date input is changed
dayLabelReactNodeLabel for the day field
dayNamestringname for the day input field
dayDefaultValueDateFieldDayDefaultValueInitial value for the day input field. Use this for an uncontrolled component; otherwise, use the dayValue property.
dayFieldRef(...args: any[]) => anyAccess a reference to the day input
dayInvalidbooleanApply error styling to the day input
dayValueDateFieldDayValueSets the day input's value. Use this in combination with onChange for a controlled component; otherwise, set dayDefaultValue.
monthLabelReactNodeLabel for the month field
monthNamestringname for the month input field
monthDefaultValueDateFieldMonthDefaultValueInitial value for the month input field. Use this for an uncontrolled component; otherwise, use the monthValue property.
monthFieldRef(...args: any[]) => anyAccess a reference to the month input
monthInvalidbooleanApply error styling to the month input
monthValueDateFieldMonthValueSets the month input's value. Use this in combination with onChange for a controlled component; otherwise, set monthDefaultValue.
yearDefaultValueDateFieldYearDefaultValueInitial value for the year input field. Use this for an uncontrolled component; otherwise, use the yearValue property.
yearFieldRef(...args: any[]) => anyAccess a reference to the year input
yearInvalidbooleanApply error styling to the year input
yearLabelReactNodeLabel for the year input field
yearNamestringname for the year field
yearValueDateFieldYearValueSets the year input's value. Use this in combination with onChange for a controlled component; otherwise, set yearDefaultValue.
classNamestringAdditional classes to be added to the root element.
idstringA unique id for the field element. Useful for referencing the field from other components with aria-describedby.
errorMessageReactNodeEnable the error state by providing an error message.
errorMessageClassNamestringAdditional classes to be added to the error message
errorIdstringThe ID of the error message applied to this field.
hintReactNodeAdditional hint text to display
inversedbooleanSet to true to apply the "inverse" theme
textClassNamestringAdditional classes to be added to the label text.
errorPlacement"top" | "bottom"Location of the error message relative to the field input
labelClassNamestringAdditional classes to be added to the field label

Styles

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

CSS variables for text-input
VariableDefault Core Theme Value
--text-input__line-height1.3
--text-input__background-color--disabledhex value: #d9d9d9--color-border
--text-input__border-width2px
--text-input__border-width--error3px
--text-input__border-width--success3px
--text-input__border-colorhex value: #262626--color-base
--text-input__border-color--disabledhex value: #a6a6a6--color-gray-light
--text-input__border-color--errorhex value: #e31c3d--color-error
--text-input__border-color--error--inversehex value: #f18e9e--color-error-light
--text-input__border-color--inversehex value: #000000--color-black
--text-input__border-color--successhex value: #2a9526--color-green-light
--text-input__colorhex value: #262626--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:

CSS variables for form
VariableDefault Core Theme Value
--form-label__color--inversehex value: #ffffff--color-white
--form__max-width460px
--form__max-width--small6em
--form__max-width--medium12em
--form-hint__colorhex value: #5a5a5a--color-gray
--form-hint__color--inversehex value: #e9ecf1--color-muted-inverse
--form-error__colorhex value: #e31c3d--color-error
--form-error__color--inversehex value: #f18e9e--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