Skip to main content
U.S. Flag

An official website of the United States government

CMS Design System

Date field (multi-input)

Jump to Guidance
View related guidance in the U.S. Web Design System

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

<MultiInputDateField>

View Source File

Code snippet

Props

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.

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.

Customization

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

VariableDefault Core Theme Value
$text-input__line-height1.3
$text-input__background-color--disabled$color-border
$text-input__border-width2px
$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

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