DatePicker

Component status

Introduction

The DatePicker component combines a date input field with a calendar popup, offering users a flexible way to select dates. It supports both keyboard and mouse interactions, with built-in validation and formatting capabilities.

When to use

Use the DatePicker component when:

• Users need to input or select dates in a standardized format
• You want to provide a visual calendar interface for date selection
• You need form-associated date input with validation
• You want to ensure consistent date formatting across your application
• You need an accessible date selection interface that works well with screen readers

Implementation

The DatePicker 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-picker/5.x.x/tt-date-picker.js"></script>

Usage

Basic usage

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

With initial value

<tt-date-picker value="2024-01-30"></tt-date-picker>

Attributes

Parts

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

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

Keyboard Navigation

Date Input

The 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

Form Integration

The DatePicker component is form-associated and will:

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

Validation

The component includes built-in validation for:

• Valid day ranges (1-31)
• Valid month ranges (1-12)
• Valid year ranges (1900-3000)
• Date existence validation (e.g., February 31st is invalid)
• Required field validation when used with required attribute

Events

Best Practices

1. Always provide clear labels for date pickers
2. Consider using placeholder text to show the expected date format
3. Implement appropriate min/max date constraints for your use case
4. Ensure sufficient space around the component for the calendar popup
5. Test keyboard navigation and screen reader compatibility
6. Consider the locale when displaying date formats

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

Example with Form

<form>
  <label for="appointment-date">Select Appointment Date</label>
  <tt-date-picker id="appointment-date" name="appointment" required></tt-date-picker>
  <button type="submit">Submit</button>
</form>

Styling

Example of custom styling:

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

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