Components
Date picker
A date picker helps users select a single date.
Testing has revealed some issues with this component. Learn more in the known issues section on this page.
<div class="usa-form-group">
<label class="usa-label" id="appointment-date-label" for="appointment-date"
>Appointment date</label
>
<div class="usa-hint" id="appointment-date-hint">mm/dd/yyyy</div>
<div class="usa-date-picker">
<input
class="usa-input"
id="appointment-date"
name="appointment-date"
aria-labelledby="appointment-date-label"
aria-describedby="appointment-date-hint"
/>
</div>
</div>
Guidance
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.
Usability guidance
- Describe the date format. Provide a hint of
mm/dd/yyyy
to help users enter the proper date format if they opt not to use the date picker.
Accessibility guidance
- Customize form controls accessibly. If you customize this component, ensure that it continues to meet the accessibility requirements that apply to all form controls.
- Avoid auto-submission. Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Auto-submission disrupts screen readers because they select each option as they read them.
- Instructions for keyboard navigation You can navigate this component using the following commands (Mac-equivalent commands are in parentheses):
- Days use left and right arrows
- Weeks use up and down arrows
- Months by using page up (fn + up arrow) and page down (fn + down arrow)
- Years by using shift + page up (shift + fn + up arrow) and shift + page down (shift + fn + down arrow)
- Home (fn + left arrow) and End (fn + right arrow) keys navigate to the beginning and end of a week
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 data-min-date
.usa-date-picker
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 or0000-01-01
is used as a default.data-max-date
.usa-date-picker
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.data-range-date
.usa-date-picker
The date picker will show a range selection from the range date. The date should be in the format
YYYY-MM-DD
. -
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 required
input
The date picker component will be required in terms of native form validation.
disabled
input
The date picker component will be disabled/readonly. You can re-enable by executing the enable procedure on the component.
data-default-value
.usa-date-picker
The date picker input will set this value if it is a valid date. The date should be in the format
YYYY-MM-DD
. -
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 enable
.usa-date-picker element
The date picker component will be enabled.
disable
.usa-date-picker element
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.
Known issues
All known issues for date picker are tracked in GitHub . Notable usability issues are tracked below:
- Users had trouble correctly typing dates in the input field. More information on GitHub: uswds#5534
Help fix these issues or add details on GitHub. Don't have an account? Please join our community to share feedback and contribute to USWDS.
Package
-
Package usage:
@forward "usa-date-picker";
- Dependencies:
uswds-fonts
,usa-icon
,usa-input
Latest updates
Meaningful code and guidance updates are listed in the following table:
Date | USWDS version | Affects | Description |
---|---|---|---|
2024-03-13 | K.A. |
|
Added known issues section. More information: uswds-site#2402 |
2024-03-11 | 3.8.0 |
|
Added focus styles to calendar button in high contrast mode.
Now, the calendar icon changes to the |
2023-11-20 | K.A. |
|
Added known issues section. More information: uswds-site#2360 |
2023-11-09 | 3.7.0 |
|
Improved keyboard navigation for screen readers. This change enables table navigation controls in the calendar, which creates more consistent and intuitive navigation across browsers and screen readers. More information: uswds#5374 |
2023-06-09 | 3.5.0 |
|
Improved legibility in forced colors mode. Adds a consistent border in forced colors mode. More information: uswds#5147 |
2023-06-09 | 3.5.0 |
|
Improved consistency and visibility of disabled styles.
Form elements with the |
2023-06-09 | 3.5.0 |
|
Improved consistency of disabled styles in forced colors mode. More information: uswds#5295 |
2023-03-09 | K.A. |
|
Updated documentation for accessibility guidance. Added instructions for keyboard navigation. More information: uswds-site#1695 |
2022-08-05 | 3.1.0 |
|
Styled aria-disabled to match disabled.
Now disabled styling is applied whether you use |
2022-06-17 | 3.0.2 |
|
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 |
2022-06-17 | K.A. |
|
Updated the documentation for initialization properties.
Changed the initialization element from |
2022-04-28 | K.A. |
|
Updated package name to |
2022-04-28 | 3.0.0 |
|
Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656 |
2022-04-13 | K.A. |
|
Updated package name to |
2022-04-11 | 2.13.3 |
|
Added support for forced colors mode. All our components now support proper display when users have a forced colors mode set in their operating system. More information: uswds#4610 |
2022-01-20 | 2.13.1 |
|
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 |
2021-12-14 | 2.13.0 |
|
Improved screen reader experience.
Now screen readers can better describe the label and description of a date picker |
2021-11-01 | 2.12.2 |
|
Added automatic sanitizing. The design system now automatically sanitizes content in elements we compose with JavaScript. This means that components like combo box, tooltip, file input, and date picker will sanitize any content passed to them. This helps protect any design system implementation against malicious XSS attacks through these components. More information: uswds#4329 |
2021-08-18 | 2.12.1 |
|
Improved performance of date picker and combo box JavaScript. More information: uswds#4256 |