A date picker helps users select a single date.
When to use the date picker component
- Scheduling. When users need to schedule or record an event and benefit from the context of a calendar.
- When the day of the week is important. When knowing the day of the week helps users choose a specific date.
When to consider something else
- Familiar dates. When asking users for a date they know well, or can look up without using a calendar (like a birthday), use memorable date fields.
- When the day of the week is irrelevant. If there’s no benefit to knowing the day of the week for a particular date, consider memorable date fields.
- Describe the date format. Provide a hint of
mm/dd/yyyyto help users enter the proper date format if they opt not to use the date picker.
- Customize form controls accessibly. If you customize this component, ensure that it continues to meet the accessibility requirements that apply to all form controls.
Using the date picker component
Properties. The following properties modify component functionality. These properties can be set or adjusted at any time before or after initialization in order to have an effect.
Property Element Description
The date picker will not allow a date selection before this date. The date should be in the format
YYYY-MM-DD. Typing in an earlier date will cause native form validation error. A default min date or
0000-01-01is used as a default.
The date picker will not allow a date selection after this date. The date should be in the format
YYYY-MM-DD. Typing in a later date will cause native form validation error. There is no default maximum date.
The date picker will show a range selection from the range date. The date should be in the format
Initialization properties. The following properties update the component during initialization. These properties must be set before the component is initialized in order to have an effect.
Property Element Description
The date picker component will be required in terms of native form validation.
The date picker component will be disabled/readonly. You can re-enable by executing the enable procedure on the component.
The date picker input will set this value if it is a valid date. The date should be in the format
Procedures. The following static procedures update the component after initialization. These are in addition to the primary methods referenced in the JS customization documentation.
Procedure Parameters Description
The date picker component will be enabled.
The date picker component will be disabled / read-only.
Date picker settings
This component has no settings.
Date picker variants
This component has no variants.
Meaningful code and guidance updates are listed in the following table:
Styled aria-disabled to match disabled.
Now disabled styling is applied whether you use
Improved date picker display at very narrow widths. We improved the display of the date picker at very narrow widths so there are no UX inconsistencies when the date picker is in a form at less than 320px width. This assures that date picker conforms to WCAG 2.1. More information: uswds#4770
Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656
Added support for high contrast mode and forced colors. All our components now support proper display when users have a forced colors mode set in their operating system. More information: uswds#4610
Fixed date picker input bug in Safari. We fixed a bug where date picker selections would not propagate into the input field in Safari. More information: uswds#4456
Improved screen reader experience.
Now screen readers can better describe the label and description of a date picker