Skip to main content
U.S. Flag

An official website of the United States government

CMS Design System

Download Code View on GitHub

Date field

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

Three text fields are the easiest way for users to enter most dates.

<DateField>

View Source File

Open in Storybook
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 format for most dates, particularly memorized dates.

When to consider alternatives

  • If users are trying to schedule something, a calendar picker might make more sense. Be sure to also provide an option for text entry as well.

Usage

  • Allow users to enter the date as flexibly as possible, for example, allowing 1 as well as 01 for a month input.
  • Be sure each field is properly labeled — some countries enter dates in day, month, year order.
  • It may be tempting to switch all or some of these text fields to drop downs, but these tend to be more difficult to use than text boxes.
  • When handling date errors, if the part of the date that has an error is known, only highlight the part with an error. For example, if month and day are valid inputs, but the year is invalid, use yearInvalid=true so that only the year field will be highlighted red.
  • If the entire date is incorrect, all fields can be highlighted. For example, if a date in the past is required and a date in the future is entered, all fields should be highlighted.

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.