Date Range Picker Specification

Revision History

Version	User	Date	Notes
2	Bozhidara Pachilova	27.08.2025	Add features and behaviors related to Alignment to WC DateRangePicker task

Konstantin Dinev | Date:
Radoslav Mirchev | Date:
Stefan Ivanov | Date:

1. Objectives

Provide an Angular native date picker widget that uses the igx-calendar and lets users input or select a date value. The display and input formats are customizable.

If the input field is editable, the user can type a date or select one from the calendar that appears in a dropdown below the input field.

Here is the basic definition of an igx-date-picker:

<igx-date-picker [(ngModel)]="date">
    <label igxLabel>Date</label>
</igx-date-picker>

The default user experience includes a readonly input that holds a single date in the following format - MM/dd/yyyy. Clicking on the input will result in a dialog pop-up that will hold a calendar from which an end user may select a value.

2. User Scenarios

2.1 As an end user

P0

Story 1: I want to be able to visually identify what day it is today – day of the week, date of the month.
Story 2: I want to be able to visually differentiate the selected date.
Story 3: I want to be able to visually differentiate business, weekend and disabled days.
Story 4: I want to be able to navigate to upcoming and past months and years in different ways. (scroll, swipe, arrows, keyboard)
Story 5: I want to be able to navigate the calendar with the keyboard.
Story 6: I want to be able to edit dates in the editor (dropdown mode).
Story 7: I want to be informed if the dates I've entered are valid and within range (if such is specified).
Story 8: I want to select a range by clicking a button among a set of predefined date ranges.

2.2 As a developer

P0

Story 1: I want to be able to implement a shortcut for the current day.
Story 2: I want be able to show and hide leading and trailing days from the previous and the following month visually identifying them as such.
Story 3: I want to be able to set the starting/first day of the week and the date format based on their locale.
Story 4: I want to have a mechanism for canceling the closing of the date picker dropdown/dialog.
Story 5: I want to have a default template which does not require any additional configuration.
Story 6: I want to be able to bind ngModel to the date picker.
Story 7: I want to be able to provide custom formatting functionality.
Story 8: I want to be able to set a label in the editor.
Story 9: I want to be able to set a placeholder in the editor.
Story 10: I want choose the component to render either single input displaying the date range values separated by a symbol ("-") or two inputs for start and end date.
Story 11: I want to define custom content for the separator between the two inputs.
Story 12: I want to set special/disabled dates in the calendar picker.
Story 13: I want to show a single or two months in the calendar picker.
Story 14: I want to listen and react to user interactions through events on the component.
Story 15: I want to opt in to show chips allowing to choose among a predefined set of ranges, such as last week, last month, etc.
Story 16: I want to define additional custom actions.
Story 17: I want to be able to style parts of the component according to my prefereces.

2.3 Acceptance criteria

All user stories must be satisfied.

3. Features

Selecting a date from the calendar.
Dropdown and dialog modes for the calendar.
Typing, pasting, dragging and dropping a date string (in a pre-defined format) into the editor with an immediate effect in the calendar.
Support for min, max, disabled and special dates.
Model binding and custom validation.
Customizable formats for the mask in and outside of edit mode.
Keyboard navigation in the editor with specified key combinations for expanding and collapsing of the calendar (dropdown mode).
Keyboard navigation in the calendar.
Highlight of today's date, customizable week start, customizable previous' and next month's visible days, customizable amount of months' views, week numbers.
Properties and templates to customized elements of the calendar, such as header and orientation.
Customizable positioning and open/close animation of the calendar.
Expanding/collapsing of the picker's calendar upon events.
ARIA support
Provide UI with buttons allowing to quickly select among a predefined set of ranges - last week, last month, etc.
Support the themes available in the library.

3.1 End user experience

Design Handoff

3.2 Developer experience

Value type

/** Represents a range between two dates. */
export interface DateRange {
    start: Date | string;
    end: Date | string;
}

Custom (predefined) date range type

/** Represents a range between two dates and a label used for predefined and custom date ranges. */
export interface CustomDateRange {
    label: string;
    dateRange: DateRange;
}

The predefined ranges chips are ported in a separate internal component named IgxPredefinedRangesAreaComponent.

Changing the label

<igx-date-picker>
    <label igxLabel>Custom Label</label>
</igx-date-picker>

Setting prefixes and suffixes

The igxPrefix and igxSuffix directives may be used to determine where the templated element will be placed.

Here is an example with the igx-icon:

<igx-date-picker #picker>
    <igx-icon igxSuffix (click)="picker.open()">
        calendar_view_day
    </igx-icon>
</igx-date-picker>

You can add multiple instances of the igxPrefix and igxSuffix directives which will stack one after the other. For example these could be used to provide the end user with the ability to spin a date portion with two buttons. Also, having projected icons like this will not affect the default toggle icon.

<igx-date-picker #picker>
    <igx-icon (click)="picker.open()" igxSuffix>expand_more</igx-icon>
    <igx-icon (click)="picker.close()" igxSuffix>expand_less</igx-icon>
</igx-date-picker>

Projecting components

The IgxPickerToggleComponent can be used as wrapper around a projected element. This adds a default click handler to it. It should also be mentioned that this acts as an override to the default toggle icon and as such it can not be stacked.

<igx-date-picker>
    <igx-picker-toggle igxPrefix>
       <igx-icon>calendar_view_day</igx-icon>
    </igx-picker-toggle>
</igx-date-picker>

Similarly, the IgxPickerClearComponent can be projected to override the default clear icon:

<igx-date-picker>
    <igx-picker-clearigxSuffix>
       <igx-icon>delete</igx-icon>
    </igx-picker-clear>
</igx-date-picker>

When a Date Range Picker has two separate inputs for start and end dates, it doesn't expose these icons by default. The IgxPickerToggleComponent and IgxPickerClearComponent should be manually added as children of the IgxDateRangeStartComponent IgxDateRangeEndComponent` like so:

<igx-date-range-picker>
    <igx-date-range-start>
        ...
        <igx-picker-toggle igxPrefix>
            <igx-icon>calendar_view_day</igx-icon>
        </igx-picker-toggle>
        <igx-picker-clear igxSuffix>
            <igx-icon>clear</igx-icon>
        </igx-picker-clear>
        ...
    </igx-date-range-start>
    <igx-date-range-end>
        ...
    </igx-date-range-end>
</igx-date-range-picker>

Templating

When two editors are used, the default separator can be replaced using the igxDateRangeSeparator directive.

<igx-date-range-picker>
    <igx-date-range-start>
...
</igx-date-range-start>
    <ng-template igxDateRangeSeparator>-</ng-template>
    <igx-date-range-end>...</igx-date-range-end>
</igx-date-range-picker>

The header, subheader and title parts of the calendar header can be customized with the igxCalendarHeader, igxCalendarSubheader and the igxCalendarHeaderTitle template directives:

<igx-date-range-picker [value]="date">
  <ng-template igxCalendarHeader let-format>
    ...
  </ng-template>
  <ng-template igxCalendarSubheader let-format>
   ...
  </ng-template>
    <ng-template igxCalendarHeaderTitle let-format>
    <span>My calendar</span>
   </ng-template>
</igx-date--range-picker>

3.3 Behaviors

General
- Default toggle and clear icons should be rendered for the single input.
- In dropdown mode and two inputs mode, clicking the toggle icon opens the calendar.
- In dialog mode and in in dropdown mode and signle input, clicking the toggle icon or the input opens the calendar.
- Clicking either the default clear icon, or a projected one clears the value.
Date input or selection
- If the picker is in a dropdown mode, selecting a date from its calendar will automatically fill in the input field with the corresponding value after which the dropdown is collapsed.
- If the picker is in a dialog mode, the user will have to press confirmation button (by default OK) which will then fill in the value in the editor. Pressing the CANCEL (by default) button will revert any selection made. Both of these buttons will result in the dialog hiding when pressed.
- The calendar shuld remain open while typing
Calendar
- Year/Month/Day navigation
- Today’s Date Highlight
- leading/trailing month days (configurable)
- First day of the week configuration support
Custom date display format
- The IgxDatePicker makes use of IgxDateTimeEditor which allows passing in of display format based on Angular DatePipe's standards.
- Custom formatting can be applied using the inputFormat property.
- In case the inputFormat property is not set, the applied input format of the underlying editor is inferred from displayFormat, if set and if it contains only numeric date-time parts.
Date Validation (min/max/disabledDates check)
- Min, max and disabled dates values can be set which can additionally configure the validity of the picker. Additionally, the calendar will display all dates that are outside of the min-max range as grayed out and they will not be selectable from its UI. If a date which is outside of the specified range is written in the editable editor, the picker will become invalid after blurring (by default).
- In scenarios when there are two inputs, both of them should reflect the form state, i.e. if the date-range-picker is invalid, both inputs should be in the invalid state.
Active date
- The calendar active date is set to activeDate property of the date-range-picker, if set.
- If the above is not set and there is no value (both start and end are null), the calendar's internal active date is used, which by default is the current date.
- If a value is assigned to the igx-date-range-picker, the first defined date among the start or end is assigned as active date:
```
 { start: *start-date*, end: null } -> // active date is *start-date*
 { start: *start-date*, end: *end-date*} -> // active date is *start-date*
 { start: null, end: *end-date*} -> // active date is *end-date*
```
- On typing in the inputs, the active date gets assigned to the last modified/typed date.
- If both values are cleared by typing, the active date remains as the last that was assigned.
Custom chips
- In dropdown mode when selecting a chip value, the dropdown gets closed.
- In dialog mode when selecting a chip value, the dialog remains opened.

3.4 Keyboard Navigation

Alt + Down Arrow - Opens the drop-down calendar and focuses it
Alt + Up Arrow - Closes the drop-down and focuses the last focused input field
Esc - Closes the drop-down and focuses the last focused input field
For keyboard navigation inside of an editable editor please refer to IgxDateTimeEditorDirective specification
For keyboard navigation inside of the calendar please refer to [IgxCalendar specification](* For keyboard navigation inside of an editable editor please refer to IgxDateTimeEditorDirective specification)

4. Test Scenarios

4.1 Interaction tests

Toggle icon should open/close the dropdown and keep current selection - both default and projected.
Clear icon should clear the value and calendar selection - both default and projected.
Alt + ArrowDown/ArrowUp keys should open/close the dropdown.
Escape key closes the dropdown discarding the selected date in the calendar.
Selecting a date from the dropdown closes the calendar and the input accepts current selection.
Clear button should reset the date value.
User is able to navigate through date parts using the arrow keys.
User is able to navigate through date parts using the mouse wheel.
Changing a date part should not affect hours, minutes, seconds and milliseconds of the selected date.
Calendar should remain open while typing (two-inputs mode, as in that case the editors are editable)

4.2 Rendering tests

All input properties are initialized with their default values.
Should be able to change the mode at runtime.
Today's date is highlighted.
Focusing in dropdown mode selects the text in the input.
When disabled the disabled class is applied to the input.
When in dialog mode a modal overlay with calendar is shown/hidden on opening/closing.
When in dropdown mode an overlay with dropdown is shown/hidden on opening/closing.
When in dropdown mode the dropdown opens below the input by default if there is enough space and above otherwise.
All aria attributes should be applied correctly.
Applies an input format on the editor as per the displayFormat property if it contains only numeric date/time parts and inputFormat is not set.
Resolves to the default locale-based input format for the editor(s) in case inputFormat or displayFromat are not set.
In dialog mode, a Cancel button should be present.
Should not render any chips when usePredefinedRanges is false and there are no custom ranges added.
Should render all predefined ranges and content in the target part of the dropdown/dialog.
Should emit valueChange when the chips are clicked.
Should render only custom chips, when usePredefinedRanges is false

4.3 API tests

The picker should update its value properly when bound with ngModel
The open() method opens the dropdown and triggers opening and opened events.
The close() method closes the dropdown and triggers closing and closed events.
The toggle() method toggles the calendar and triggers opening and closing events.
The select() method selects a date from the calendar and fires valueChange event.
The clear() method sets the value to null, emits valueChange and sets the value to null.
Opening and closing events are cancelable.
If set, minValue,maxValue and disabledDates should determine the picker's valid state.

5. API

5.1 Options

Name	Type	Description
id	string	`attr.id` of the picker.
mode	InteractionMode	Sets whether `IgxDatePickerComponent` is in dialog or dropdown mode.
value	Date	The value of the editor.
minValue	Date \| string	The minimum value required for the picker to remain valid.
maxValue	Date \| string	The maximum value required for the editor to remain valid.
displayFormat	string	The display value of the editor.
inputFormat	string	The format that the editor will use to display the date/time.
formatOptions	IFormatOptions	The calendar's format options for the day view.
specialDates	DateRangeDescriptor[]	Dates that will be marked as special in the calendar.
disabledDates	DateRangeDescriptor[]	Dates that will be disabled in the calendar.
formatViews	IFormatViews	Determines if `day`, `month` and `year` will be rendered in the calendar. `locale` and `formatOptions` are taken into account as well, if present.
displayMonthsCount	number	Sets the number of displayed month views. Default is `2`.
hideOutsideDays	boolean	Sets whether dates that are not part of the current month will be displayed. Default is `false`.
showWeekNumbers	number	Shows or hides week numbers.
tabindex	number	The editor's tabindex
weekStart	number	Sets the start day of the week. If `weekStart` is not explicitly set, its value to be determined based on the calendar `locale` value, using `getLocaleFirstDayOfWeek`
locale	string	Locale settings used in displayFormat. If this `locale` is not set, its value to be determined based on the global Angular application `LOCALE_ID`.
overlaySettings	OverlaySettings	Changes the default overlay settings used by the `IgxDatePickerComponent`.
placeholder	string	Sets the placeholder text for an empty input.
disabled	boolean	Disables or enables the picker.
outlet	IgxOverlayOutletDirective \| ElementRef	The container used for the pop up element.
type	IgxInputGroupType	Determines how the picker will be styled.
hideHeader	`boolean`	Whether to show the calendar header. Applicable only in dialog mode
headerOrientation	`'vertical' \| 'horizontal'`	Whether to align the calendar header vertically or horizontally. Applicable only in dialog mode.
orientation	`'vertical' \| 'horizontal'`	Whether to align multiple months horizontally or vertically
activeDate	Date	Sets the active date of the calendar

5.2 Methods

Name	Type	Description
select	void	Accepts a Date object and selects the corresponding date from the calendar.
clear	void	Clears the picker's input.
open	void	Opens the calendar.
close	void	Closes the calendar.
toggle	void	Toggles the calendar between opened and closed state.

5.3 Events

Name	Emitted with	Description
opening	IBaseCancelableBrowserEventArgs	Fired when the calendar has started opening, cancelable.
opened	IBaseEventArgs	Fired after the calendar has opened.
closing	IBaseCancelableBrowserEventArgs	Fired when the calendar has started closing, cancelable.
closed	IBaseEventArgs	Fired after the calendar has closed.
valueChange	Date	Emitted when the picker's value changes.

API Reference:

6. ARIA Support

The IgxDatePickerComponent is decorated with the following properties:

role is combobox
aria-haspopup is dialog
aria-expanded - which shows if the calendar container is visible
aria-labelledby - which relates to a specified label
aria-autocomplete is off to prevent the browser from remembering previous inputs (when editable)
the default toggle icon has two variants for aria-label:
- in dialog mode it has a prompt text such as Choose Date if there is no selected date; selecting any date from the calendar will change that to Change Date as well as the currently chosen date which is in the picker's specified format
- in dropdown mode it holds the Choose Date prompt and after selecting a date from the calendar will change to Change Date; it should also be excluded from the TAB sequence
aria-required is true if the picker has been marked as required