DateRangePicker

Component status

	Status
Is the design finished and component available in Figma library?	Update required
Is the design documentation complete?	Update required
Is the technical documentation complete?	Up to date

Introduction

The DateRangePicker component combines date input fields with a calendar popup, enabling users to select a range of dates. It supports both keyboard and mouse interactions, with built-in validation and range constraints.

When to use

Use the DateRangePicker component when:

Users need to select a span of dates (e.g., for booking periods or report ranges)
You need to enforce minimum or maximum duration constraints
You want to provide preset date ranges (e.g., "Last 7 days", "This month")
You need form-associated date range input with validation
You need an accessible date range selection interface that works well with screen readers

Implementation

The DateRangePicker is implemented as a Web Component following WAI-ARIA best practices. Import it using:

<script type="module" src="https://cdn.design-system.triptease.io/tt-date-range-picker/latest/tt-date-range-picker.js"></script>

Basic Usage

<tt-date-range-picker></tt-date-range-picker>

With constraints:

<tt-date-range-picker 
  min-days="2"
  max-days="30"
  min-date="2024-01-01"
  max-date="2024-12-31">
</tt-date-range-picker>

Attributes

Attribute	Type	Default	Description
`start`	Date	undefined	Start date of the range
`end`	Date	undefined	End date of the range
`min-days`	number	undefined	Minimum number of days in the range
`max-days`	number	undefined	Maximum number of days in the range
`min-date`	Date	undefined	Earliest selectable date
`max-date`	Date	undefined	Latest selectable date

Parts

The component uses Shadow DOM and exposes the following parts for styling:

controls: The outer container wrapper for inputs and calendar button
error: The error message container
calendar: The calendar popup container

Keyboard Navigation

Date Input Fields

Each date input field supports the following keyboard interactions:

Tab: Navigate between day, month, and year fields
Up/Down arrows: Increment/decrement the current field value
Forward slash (/): Move to the next field
Backspace: Clear the current field, move to previous field if empty
Enter: Move to next field, submit when in year field

Calendar

When the calendar popup is open:

Arrow keys: Navigate between dates
Enter/Space: Select the focused date
Escape: Close the calendar
Page Up: Previous month
Page Down: Next month
Shift + Page Up: Previous year
Shift + Page Down: Next year
Home: Move to first day of week
End: Move to last day of week

Preset Ranges

The calendar includes preset range options:

This week
Last week
This month
Last month
This quarter
Year to date

Form Integration

The DateRangePicker component is form-associated and will:

Participate in form submission with proper date values
Support form validation
Display validation messages for invalid ranges
Support form reset functionality

Validation

The component includes built-in validation for:

End date must be after start date
Minimum days constraint (if specified)
Maximum days constraint (if specified)
Minimum date constraint (if specified)
Maximum date constraint (if specified)
Valid day ranges (1-31)
Valid month ranges (1-12)
Valid year ranges (1900-3000)
Date existence validation (e.g., February 31st is invalid)

Events

Event	Detail Type	Description
`change`	DateRange	Fired when a date range is input manually
`date-range-selection`	DateRange	Fired when a date range is selected from the calendar

The DateRange type has the following structure:

interface DateRange {
  startDate?: Date;
  endDate?: Date;
}

Best Practices

Always provide clear labels for start and end dates
Set appropriate min/max day constraints for your use case
Choose sensible min/max date constraints to limit selection range
Ensure error messages clearly explain validation failures
Test keyboard navigation and screen reader compatibility
Consider the locale when displaying date formats
Provide helpful preset ranges for common use cases

Accessibility

Uses proper ARIA roles and attributes
Supports keyboard navigation
Provides clear error messages
Calendar popup is properly announced to screen readers
Date format is clearly communicated
Visual focus indicators for all interactive elements
Preset ranges are keyboard accessible

Example with Validation

<form>
  <label for="booking-dates">Select Booking Dates</label>
  <tt-date-range-picker 
    id="booking-dates"
    name="booking"
    min-days="2"
    max-days="14"
    min-date="2024-01-01"
    max-date="2024-12-31"
    required>
  </tt-date-range-picker>
  <button type="submit">Book Now</button>
</form>

Styling

Example of custom styling:

tt-date-range-picker::part(controls) {
  border-color: var(--color-primary-500);
  border-radius: var(--border-radius-md);
}

tt-date-range-picker::part(error) {
  color: var(--color-error-500);
  font-size: var(--font-size-sm);
}