Date range picker

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

mm/dd/yyyy
mm/dd/yyyy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<form class="usa-form">
  <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" type="text" aria-describedby="event-date-start-label 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" type="text" aria-describedby="event-date-end-label event-date-end-hint">
      </div>
    </div>
  </div>
</form>

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 date input 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

  • Customize accessibly. If you customize the date picker, ensure it continues to meet the 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.

Implementation

  • 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 effect
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 or 0000-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 an later date will cause native form validation error. There is no default maximum date.
Date range picker settings

This component has no settings.

Date range picker variants

This component has no variants.

Package information

  • Package usage: @import form-controls
  • Requires: required, global