Components

Date range picker

A date range picker helps users select a range between two dates.

Testing has revealed some issues with this component. Learn more in the known issues section on this page.

mm/dd/yyyy
mm/dd/yyyy

<div class="usa-date-range-picker">
  <div class="usa-form-group">
    <label class="usa-label" id="event-date-start-label" for="event-date-start"
      >Event start date</label
    >
    <div class="usa-hint" id="event-date-start-hint">mm/dd/yyyy</div>
    <div class="usa-date-picker">
      <input
        class="usa-input"
        id="event-date-start"
        name="event-date-start"
        aria-labelledby="event-date-start-label"
        aria-describedby="event-date-start-hint"
      />
    </div>
  </div>
  <div class="usa-form-group">
    <label class="usa-label" id="event-date-end-label" for="event-date-end"
      >Event end date</label
    >
    <div class="usa-hint" id="event-date-end-hint">mm/dd/yyyy</div>
    <div class="usa-date-picker">
      <input
        class="usa-input"
        id="event-date-end"
        name="event-date-end"
        aria-labelledby="event-date-end-label"
        aria-describedby="event-date-end-hint"
      />
    </div>
  </div>
</div>

Guidance

When to use the date range 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

  • When the day of the week is irrelevant. If there’s no benefit to knowing the day of the week for a date or range, 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.
  • Always allow a user to type in the date manually. Usability testing suggests some people prefer manually typing the date rather than using the calendar picker. Whenever possible, keep the keyboard active so people can enter in the date information without having to use the 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.

Using the date range 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-range-picker

    The date range 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-01 is used as a default.

    data-max-date

    .usa-date-range-picker

    The date range picker will not allow a date selection after this date. The date should be in the format YYYY-MM-DD. Typing in an later date will cause native form validation error. There is no default maximum date.

  • 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 range picker settings

This component has no settings.

Date range picker variants

This component has no variants.

Known issues

All known issues for date range 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-range-picker";
  • Dependencies: usa-date-picker

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-11-19 N/A
  • Guidance
 No

Added guidance about always allowing users to type in the date manually. More information: uswds-site#2822

2024-10-04 3.9.0
  • Accessibility
  • JavaScript
 No

Fixed a bug that caused mouseover events to prevent keyboard navigation. Now when you hover your mouse over the date picker buttons, only the hover state will be triggered. More information: uswds#5774

2024-10-04 3.9.0
  • Accessibility
  • JavaScript
 No

Added aria-disabled to the list of expected attributes. Now, the component will disable toggle when the aria-disabled attribute is present. More information: uswds#6013

2024-06-07 N/A
  • Guidance
 No

Added known issues section. More information: uswds-site#2620

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency and visibility of disabled styles. Form elements with the disabled or aria-disabled attribute now get consistent styling and have proper color contrast. More information: uswds#5063

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency of disabled styles in forced colors mode. More information: uswds#5295

2022-08-05 3.1.0
  • Accessibility
  • Styles
 No

Styled aria-disabled to match disabled. Now disabled styling is applied whether you use disabled (disabled and hidden from screen readers) or aria-disabled (disabled and visible to screen readers). More information: uswds#4783

2022-06-17 3.0.2
  • Accessibility
  • Styles
 No

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 N/A
  • Guidance
 No

Updated the documentation for initialization properties. Changed the initialization element from select to input. More information: uswds-site#1605

2022-06-17 N/A
  • Guidance
 No

Updated the documentation for properties. Changed the element from .usa-date-picker to .usa-date-range-picker. More information: uswds-site#1605

2022-04-28 N/A
  • Guidance
 No

Updated package name to usa-date-range-picker. More information: uswds-site#1538

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2022-04-13 N/A
  • Guidance
 No

Updated package name to form-controls. More information: uswds-site#1497

2022-04-11 2.13.3
  • Accessibility
  • Styles
 No

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
  • JavaScript
 No

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
  • Accessibility
  • Markup
 No

Improved screen reader experience. Now screen readers can better describe the label and description of a date picker input. More information: uswds#4414

2021-11-01 2.12.2
  • JavaScript
 No

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
  • JavaScript
 No

Improved performance of date picker and combo box JavaScript. More information: uswds#4256