Github

Range Date Picker

Range date pickers let users select a start date and end date together.

Component Variations

Basic Range Date Picker

Date picker for selecting a date range

States

Contains: Default, Success, Error, Warning

Date range is valid
Invalid date range
Check date range

Dropdown Positions

Contains: Bottom-Left, Bottom-Center, Bottom-Right, Top-Left, Top-Center, Top-Right

Input Field Variations

Contains: Optional Label, Hint Text, Helper Text, Leading Icon

Optional

This is helper text shown below the input field

Optional

Helper text displayed below the field

Usage Guidelines

1. Import

Import the range date picker component:

import-range-date-picker.ts

Copy code

2. Basic Usage

Simplest form of the range date picker:

basic-usage-example.html

Copy code

3. Dropdown Position

Control the calendar dropdown position:

dropdown-position-example.html

Copy code

4. All API Usage

Comprehensive example with all available properties and events:

range-date-picker-all-api.html

Copy code

API Reference

Inputs

Properties that can be passed to the component:

Property
Type
Default
Required
Description
label
string
-
No
Label text displayed above the date range picker
placeholder
string
'Select date range'
No
Placeholder text shown when no date range is selected
value
DateRange | null
null
No
Currently selected date range with start and end dates
disabled
boolean
false
No
Whether the date range picker is disabled
optional
boolean
false
No
Whether the date range picker is optional
state
'success' | 'error' | 'warning' | null
null
No
Visual state of the date range picker
helperText
string
-
No
Helper text displayed below the date range picker
hintText
string
-
No
Hint text displayed in tooltip on ? icon next to label
dropdownPosition
'bottom-left' | 'bottom-center' | 'bottom-right' | 'top-left' | 'top-center' | 'top-right'
'bottom-left'
No
Position of the dropdown calendar relative to the input field
minDate
Date
-
No
Minimum selectable date

Outputs

Events emitted by the component:

Property
Type
Description
Format
valueChange
EventEmitter<DateRange | null>
Emitted when the selected date range changes
{ start: Date | null, end: Date | null } or null
inputFocus
EventEmitter<void>
Emitted when the input receives focus
No payload
inputBlur
EventEmitter<void>
Emitted when the input loses focus
No payload

Inputs

Property
Type
Default
Required
Description
label
string
-
No
Label text displayed above the date range picker
placeholder
string
'Select date range'
No
Placeholder text shown when no date range is selected
value
DateRange | null
null
No
Currently selected date range with start and end dates
disabled
boolean
false
No
Whether the date range picker is disabled
optional
boolean
false
No
Whether the date range picker is optional
state
'success' | 'error' | 'warning' | null
null
No
Visual state of the date range picker
helperText
string
-
No
Helper text displayed below the date range picker
hintText
string
-
No
Hint text displayed in tooltip on ? icon next to label
dropdownPosition
'bottom-left' | 'bottom-center' | 'bottom-right' | 'top-left' | 'top-center' | 'top-right'
'bottom-left'
No
Position of the dropdown calendar relative to the input field
minDate
Date
-
No
Minimum selectable date

DateRange Interface

The value property accepts an object with the following structure:

date-range-interface.ts

Copy code

Best Practices

When to Use

  • Use Range Date Picker when this pattern clearly supports the user task.
  • Use it to keep similar interactions consistent across the product.

When Not to Use

  • Avoid using Range Date Picker when a simpler component communicates the same intent.
  • Avoid using it when the pattern introduces unnecessary interaction steps.

Design Guidelines

  • Always provide clear labels indicating that a date range is expected
  • Use helper text to clarify the date range format or constraints
  • Set min and max dates to constrain valid selections
  • Use state prop to provide validation feedback for invalid ranges
  • Consider pre-selecting common date ranges (last 7 days, last month, etc.)
  • Validate that the end date is after the start date
  • Provide meaningful error messages for invalid date range selections
  • Consider the typical use case when choosing dropdown position
  • Use consistent date formats across your application
  • Keep labels, helper text, and actions concise and easy to scan.
  • Use VD variants and states consistently for predictable behavior.
  • Ensure keyboard access and clear focus order for accessibility.

Playground

Customize the range date picker features

example.html

Copy code