Date range

ECT approvedUpdated May 21, 2026

Description

A date range captures a start date and an end date selected or entered by a user.
Use it to let a user:
filter table data by start and end date.
set 2 dates that are related to each other. For example, a hotel booking.

Figma library

Usability test results

Anatomy

There are 2 types of date range component, standard and advanced.

Standard

Size

Both standard and advanced date range are available in S , M and L sizes.
The calendar size is the same for each date range size.

States

Warning

States are visual indicators used to communicate a component’s interaction status. Learn more about commonly used component states in our General specs

Component-specific states

A date range consists of 2 date pickers, or a dropdown select with date range presets.

Learn about date picker states

Learn about dropdown select states

Variations

Advanced date range

Includes a single input (dropdown select) with date range preset options and a custom range option.

The date input area is empty until a user selects or enters a date range.
The advanced variation is presented as an additional option, not a replacement for existing individual options.

With simple option presets

With complex option presets (grouped)

Advanced date range behavior

Using the advanced date range

Best practices

Allow a user to enter dates in shorthand or common formats. Convert dates to a format accepted by the database behind the scenes. See guidelines for capturing numeric data
Do not use placeholder text as it can cause usability and accessibility issues. Use a descriptive label and hint text instead. See guidelines for using placeholder text
Make sure the open calendar does not hide the text input.
Highlight dates in the calendar that have an event or are unavailable.
Change a permanently read-only date field to formatted text with no field border.
Use manual activation for a date range. The date range calendar is displayed only when a user selects the date range using Space or Enter on the keyboard, or a mouse click.

Technical example

Date range component implemented in Carbon.

Localization

Follow local date format conventions. For example:

North America: month day, year.
Ireland and UK: day month year.

Labels

For months and days of the week, use three-letter abbreviations with initial capitalization and no period.
Mon, Tue, Wed, Thu, Fri, Sat, Sun
Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
If space is limited, you can use one-letter or two-letter abbreviations for days of the week.
Su, Mo, Tu, We, Th, Fr, Sa
S, M, T, W, T, F, S

Hint text

Avoid non-numeric formatting hints like DD/MM/YYYY as they can be confusing for some users with lower digital literacy. Use a real date instead. For example, 15/07/2025.
Use For example instead of “e.g.” as some users might not understand the abbreviation.

Error messages

Avoid using current date. Instead, use today's date.
Spell out the month.
Learn more in the error messages pattern

Error message examples for dates

Use case	Example error messages
No date in a required date input.	Enter a date of birth.
The date is incomplete.	Enter a date that includes a month.Enter a date that includes a day and month.Enter a year in the format XXXX.
The date is not correct. For example, 13/13/13.	Enter a month that is between 1 and 12.
The date is in the future but needs to be today or in the past.	Enter a date that is today or in the past.
The date is in the past but needs to be today or in the future.	Enter a date that is today or in the future.
The date must be after another date.	Enter a date that is after 1 September 2024.
The date must be between 2 dates.	Enter a date that is between 1 September 2024 and 30 September 2024.

Requirements

Users should be able to:

Navigate between two date pickers using assistive technology.
Select or enter two dates using multiple input methods.

Interactions

Users should be able to select or enter two dates using the date range component. For more detailed information on interactions, see the Date picker component

Keyboard interactions

Tab. Moves focus from the previous interactive element on the page to the leading date picker.
Pressing tab again moves focus to the trailing date picker.
Arrow down. Opens the calendar popover on either date picker.

Design considerations

Make sure each of the date pickers has a clear, visible label.
Use hint text to help users know what date format to use.

Development considerations

For more detailed information about development considerations, see the Date picker component

Each date picker is marked up as a combobox with the calendar popover having a role=”dialog”.
Each date picker should have a clear, accessible name, conveyed by a label with a for attribute pointing to the unique id of the input.
Use role=”group” to wrap the two date pickers, so screen reader users can clearly understand the relationship between them.
Make sure hint text is associated with inputs using an aria-describedby pointing to the id of the hint text.

Date	Changes
August 2025	Updated guidance on the accessibility tab.
September 2024	New version created. Previous version archived in the frozen Product design system.