diff --git a/apiMap/WebComponents/webInputs.JS.wc.apiMap.json b/apiMap/WebComponents/webInputs.JS.wc.apiMap.json index c3c3a3f0a..d3e8f5626 100644 --- a/apiMap/WebComponents/webInputs.JS.wc.apiMap.json +++ b/apiMap/WebComponents/webInputs.JS.wc.apiMap.json @@ -27,6 +27,7 @@ "igc-circular-progress-module.ts", "igc-combo-module.ts", "igc-date-picker-module.ts", + "igc-date-range-picker-module.ts", "igc-date-time-input-module.ts", "igc-dialog-module.ts", "igc-divider-module.ts", @@ -213,6 +214,58 @@ {"names":[{"platform": "WebComponents", "mappedType": "number", "mappedName": "visibleMonths"}], "originalName": "VisibleMonths"}, {"names":[{"platform": "WebComponents", "mappedType": "WeekDays","mappedName": "weekStart"}], "originalName": "WeekStart"} ] }, + { + "originalName": "DateRangePicker", + "originalNamespace": "Infragistics.Controls", + "originalBaseTypeNamespace": "Infragistics.Controls", + "originalBaseTypeName": "BaseComboBoxLike", + "packageName": "igniteui-webinputs", + "names":[{"platform": "WebComponents","fileName": "igc-date-range-picker-component.ts","mappedName": "IgcDateRangePickerComponent"}], + "members":[ + {"names":[{"platform": "WebComponents", "mappedType": "boolean","mappedName": "open"}], "originalName": "Open"}, + {"names":[{"platform": "WebComponents", "mappedType": "string", "mappedName": "mode"}], "originalName": "Mode"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean", "mappedName": "keepOpenOnSelect"}], "originalName": "KeepOpenOnSelect"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean", "mappedName": "keepOpenOnOutsideClick"}], "originalName": "KeepOpenOnOutsideClick"}, + {"names":[{"platform": "WebComponents", "mappedType": "DateRangeValue","mappedName": "value"}], "originalName": "Value"}, + {"names":[{"platform": "WebComponents", "mappedType": "Date", "mappedName": "min"}], "originalName": "Min"}, + {"names":[{"platform": "WebComponents", "mappedType": "Date","mappedName": "max"}], "originalName": "Max"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean", "mappedName": "required"}], "originalName": "Required"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean", "mappedName": "disabled"}], "originalName": "Disabled"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean", "mappedName": "readOnly"}], "originalName": "ReadOnly"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean", "mappedName": "nonEditable"}], "originalName": "NonEditable"}, + {"names":[{"platform": "WebComponents", "mappedType": "string", "mappedName": "placeholder"}], "originalName": "Placeholder"}, + {"names":[{"platform": "WebComponents", "mappedType": "string", "mappedName": "placeholderStart"}], "originalName": "PlaceholderStart"}, + {"names":[{"platform": "WebComponents", "mappedType": "string","mappedName": "placeholderEnd"}], "originalName": "PlaceholderEnd"}, + {"names":[{"platform": "WebComponents", "mappedType": "string","mappedName": "label"}], "originalName": "Label"}, + {"names":[{"platform": "WebComponents", "mappedType": "string","mappedName": "labelStart"}], "originalName": "LabelStart"}, + {"names":[{"platform": "WebComponents", "mappedType": "string", "mappedName": "labelEnd"}], "originalName": "LabelEnd"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean", "mappedName": "outlined"}], "originalName": "Outlined"}, + {"names":[{"platform": "WebComponents", "mappedType": "string","mappedName": "locale"}], "originalName": "Locale"}, + {"names":[{"platform": "WebComponents", "mappedType": "string", "mappedName": "inputFormat"}], "originalName": "InputFormat"}, + {"names":[{"platform": "WebComponents", "mappedType": "string", "mappedName": "displayFormat"}], "originalName": "DisplayFormat"}, + {"names":[{"platform": "WebComponents", "mappedType": "string", "mappedName": "prompt"}], "originalName": "Prompt"}, + {"names":[{"platform": "WebComponents", "mappedType": "string", "mappedName": "weekStart"}], "originalName": "WeekStart"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean", "mappedName": "showWeekNumbers"}], "originalName": "ShowWeekNumbers"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean", "mappedName": "hideOutsideDays"}], "originalName": "HideOutsideDays"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean","mappedName": "hideHeader"}], "originalName": "HideHeader"}, + {"names":[{"platform": "WebComponents", "mappedType": "string", "mappedName": "headerOrientation"}], "originalName": "HeaderOrientation"}, + {"names":[{"platform": "WebComponents", "mappedType": "string", "mappedName": "orientation"}], "originalName": "Orientation"}, + {"names":[{"platform": "WebComponents", "mappedType": "number", "mappedName": "visibleMonths"}], "originalName": "VisibleMonths"}, + {"names":[{"platform": "WebComponents", "mappedType": "DateRangeDescriptor[]", "mappedName": "disabledDates"}], "originalName": "DisabledDates"}, + {"names":[{"platform": "WebComponents", "mappedType": "DateRangeDescriptor[]", "mappedName": "specialDates"}], "originalName": "SpecialDates"}, + {"names":[{"platform": "WebComponents", "mappedType": "Date","mappedName": "activeDate"}], "originalName": "ActiveDate"}, + {"names":[{"platform": "WebComponents", "mappedType": "method", "mappedName": "resourceStrings"}], "originalName": "ResourceStrings"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean", "mappedName": "useTwoInputs"}], "originalName": "UseTwoInputs"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean","mappedName": "usePredefinedRanges"}], "originalName": "UsePredefinedRanges"}, + {"names":[{"platform": "WebComponents", "mappedType": "CustomDateRange[]", "mappedName": "customRanges"}], "originalName": "CustomRanges"}, + {"names":[{"platform": "WebComponents", "mappedType": "method", "mappedName": "show"}], "originalName": "Show"}, + {"names":[{"platform": "WebComponents", "mappedType": "method", "mappedName": "hide"}], "originalName": "Hide"}, + {"names":[{"platform": "WebComponents", "mappedType": "method", "mappedName": "toggle"}], "originalName": "Toggle"}, + {"names":[{"platform": "WebComponents", "mappedType": "method", "mappedName": "clear"}], "originalName": "Clear"}, + {"names":[{"platform": "WebComponents", "mappedType": "method","mappedName": "select"}], "originalName": "Select"}, + {"names":[{"platform": "WebComponents", "mappedType": "method", "mappedName": "setCustomValidity"}], "originalName": "SetCustomValidity"} + ] + }, { "originalName": "Divider", "originalNamespace": "Infragistics.Controls", diff --git a/doc/en/components/scheduling/date-range-picker.md b/doc/en/components/scheduling/date-range-picker.md new file mode 100644 index 000000000..dc2af4eef --- /dev/null +++ b/doc/en/components/scheduling/date-range-picker.md @@ -0,0 +1,445 @@ +--- +title: {Platform} Date Range Picker Component - {ProductName} +_description: Infragistics' {Platform} Date Range Picker allows the user to select a range of two dates from a calendar and set it in an input element. +_keywords: {Platform} Date Range Picker, {ProductName}, Infragistics +mentionedTypes: ["DateRangePicker"] +--- + +# {Platform} Date Range Picker Overview +The {ProductName} Date Range Picker is a lightweight component that includes a text input and a calendar pop-up, allowing users to easily select start and end dates. It is highly customizable to fit various application requirements, offering features such as date range restrictions, configurable date formats, and more. + +## Date Range Picker Example + +Below is a sample demonstrating the `DateRangePicker` component in action, where a calendar pop-up allows users to select start and end dates. + +`sample="/scheduling/date-range-picker/overview", height="500", alt="{Platform} Date Range Picker Overview Example"` + +### Getting Started + + + +To start using the `DateRangePicker`, you first need to install the Ignite UI for Web Components by running the following command: + +```cmd +npm install {PackageWebComponents} +``` + +After that, you need to import the `DateRangePicker`, its necessary CSS, and register its module, as follows: + +```ts +import { defineComponents, IgcDateRangePickerComponent } from 'igniteui-webcomponents'; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; + +defineComponents(IgcDateRangePickerComponent); +``` + + + +Now you can start with a basic configuration of the {Platform} `DateRangePicker`. + +For a complete introduction to the {ProductName}, read the [*Getting Started*](../general-getting-started.md) topic. + +## Usage + +The `DateRangePicker` allows users to select a start and end date either by choosing a date range from a dropdown/calendar pop-up or by typing directly into the input fields - one for the start date and one for the end date. + +The picker offers two modes for displaying date values: single input and two inputs. In single input mode, the field is non-editable, and the date range cannot be edited by typing. In two inputs mode, however, users can edit the start and end dates by typing in separate input fields. + +When the calendar is visible, a date range can be selected by choosing both a start and end date. Selecting a date will set both the start and end date, and once a second date is chosen, it will set the end date. If a range is already selected, clicking any other date on the calendar will start a new range selection. + +### Display Date Range Picker + +To instantiate a `DateRangePicker` in its default single input mode, use the following code: + +```html + + +``` + +To switch the `DateRangePicker` to use two inputs, set the `UseTwoInputs` property to `true`. + +```html + + +``` + +### Value + +In addition to being selected or typed by the user, the range value of the `DateRangePicker` can also be set using the `Value` property. It's important to note that the value must follow the format: **{ start: startDate, end: endDate }**, where `startDate` and `endDate` are `Date` objects representing the selected range. + +```ts +let dateRange = document.querySelector('igc-date-range-picker') as IgcDateRangePickerComponent; +let startDate = new Date(2025, 4, 6); +let endDate = new Date(2025, 4, 8); +dateRange.value = { start: startDate, end: endDate } +``` + +In addition, the value can be set as attribute. In this case it should represent an object that can be parsed correctly as JSON, where the `start` and `end` fields should have date values in the ISO 8601 format: + +```html + + +``` + +### Read-only & Non-editable + +You can also make the `DateRangePicker` read-only, which disables changing the range value through both typing and calendar selection, disables keyboard navigation, and makes the calendar and clear icons appear visually disabled. This is useful when the range is assigned via the value attribute and is intended to be display-only. To enable this behavior, simply set the `ReadOnly` property. + +```html + + +``` + +Alternatively, you can use the `NonEditable` property, which, unlike `ReadOnly`, only prevents editing the input(s) via typing, while still allowing selection through the calendar and clearing via the clear icon. + +```html + + +``` + +### Popup modes + +By default, when clicked, the `DateRangePicker` opens its calendar pop-up in `dropdown` mode. Alternatively, the calendar can be opened in `dialog` mode by setting the `Mode` property to `dialog`. + +```html + + +``` + +### Keyboard Navigation + +The `DatePicker` features intuitive keyboard navigation, allowing users to easily increment, decrement, or jump between different component parts, all without needing to use a mouse. + +The available keyboard navigation options vary depending on whether the component is in single input or two inputs mode. + +**Two Inputs Mode:** + +|Keys|Description| +|----|-----------| +| ← | Moves the caret one character to the left | +| → | Moves the caret one character to the right | +| Ctrl + ArrowLeft | Moves the caret to the beginning of the current input mask section or to the start of the previous one if it's already at the beginning | +| Ctrl + ArrowRight | Moves the caret to the end of the current input mask section or to the end of the next one if it's already at the end | +| ArrowUp | Increments the currently "focused" part of the input mask by one step | +| ArrowDown | Decrements the currently "focused" part of the input mask by one step | +| Home | Moves the caret to the beginning of the input mask | +| End | Moves the caret to the end of the input mask | +| Ctrl + ; | Sets the current date as the value of the component | + +**Both Single and Two Inputs Modes:** + +|Keys|Description| +|----|-----------| +| Alt + ArrowDown | Opens the calendar dropdown | +| Alt + ArrowUp | Closes the calendar dropdown | + +You can also navigate within the calendar pop-up using the keyboard. The navigation is the same as in the `Calendar` component. + +|Keys|Description| +|----|-----------| +| ↑ / ↓ / ← / →| Navigates through the days in the month | +| ENTER | Selects the currently focused day | +| PageUp | Moves to the previous month's view | +| PageDown | Moves to the next month's view | +| SHIFT + PageUp | Moves to the previous year | +| SHIFT + PageDown | Moves to the next year | +| Home | Focuses the first day of the current month that is in view (or earliest month when more than one month view is displayed) | +| End | Focuses the last day of the current month that is in view. (or latest month when more than one month view is displayed) | +| Escape | Closes the calender pop-up | + +## Layout + +### Label + +You can define a label for the `DateRangePicker` component using the `Label` property when it is in single input mode. In two inputs mode, you can use the `LabelStart` and `LabelEnd` properties to define labels for the start and end date input fields, respectively. + +```html + + +``` + +```html + + +``` + +### Format + +You also have the option to customize the date format displayed in the input fields. There are three properties available for this purpose: `Locale`, `InputFormat`, and `DisplayFormat`. + +The `Locale` property allows you to set the desired locale identifier, which determines how the date is formatted based on regional conventions. +For example, to display the date in a Japanese format, you can set the locale property like this: +```html + + +``` + +If you want to manually define the date format, you can use the `InputFormat` property by passing a custom format string: + +```html + + +``` + +The `DisplayFormat` property also accepts a custom format string, but it only applies when the input field is idle (i.e., not focused). When the field is focused, the format reverts to the default or to the one defined by `InputFormat`, if both properties are used together: + +```html + + +``` + +### Calendar Layout and Formatting + +You can further customize the pop-up calendar using various properties: + +|Name|Type|Description| +|--|--|--| +| `Orientation` | 'vertical' or 'horizontal' | Allows you to set whether the calendar should be displayed vertically or horizontally. | +| `VisibleMonths` | string | Controls how many months are visible at a time, with a value of either 1 or 2. | +| `ShowWeekNumbers` | string | Enables or disables the week number column in the calendar. | +| `Open` | boolean | Determines whether the calendar picker is open. | +| `KeepOpenOnSelect` | boolean | Keeps the calendar picker open after a date selection. | +| `KeepOpenOnOutsideClick` | boolean | Keeps the calendar picker open when clicking outside of it. | +| `WeekStart` | string | Sets the start day of the week. | +| `HideOutsideDays` | boolean | Hides days that fall outside the current month view. | +| `HideHeader` | boolean | Hides the calendar header (applicable only in dialog mode). | +| `HeaderOrientation` | 'vertical' or 'horizontal' | Aligns the calendar header vertically or horizontally (dialog mode only). | +| `ActiveDate` | Date | Sets the date that is initially highlighted in the calendar. If not set, the current date becomes the active date. | + +```html + + +``` + +### Min & Max + +You can also set the `Min` and `Max` properties to restrict user input by disabling calendar dates outside the defined range. These properties act as validators, so even if the user manually types a date outside the range, the `DateRangePicker` will become invalid. + +```html + + +``` + +### Custom & Predefined Date Ranges + +You can also add custom date range chips to the calendar pop-up for faster range selection using the `CustomRanges` property. For example, you can create a custom date range chip to quickly select the range for the previous 7 days, ending with the current date. In addition, by setting the `UsePredefinedRanges` property, a set of predefined ranges chips will be displayed along with the custom ones. + +```ts +const today = new Date(); + +const previousSeven = new Date( + today.getFullYear(), + today.getMonth(), + today.getDate() - 7 +); +const lastWeek: CustomDateRange[] = [ + { + label: 'Previous 7 days', + dateRange: { + start: previousSeven, + end: today, + }, + } +] + +const dateRange = document.querySelector('igc-date-range-picker') as IgcDateRangePickerComponent; +dateRange.customRanges = lastWeek; +dateRange.usePredefinedRanges = true; +``` + +Now, when you click the newly created `"Previous 7 days"` chip in the calendar pop-up, the range will automatically be selected, starting from 7 days ago and ending today. + +`sample="/scheduling/date-range-picker/custom-ranges", height="500", alt="{Platform} Date Range Picker Custom Ranges Example"` + +### Disabled & Special dates + +You also have the ability to set disabled dates in the calendar to narrow the range of dates the user can choose from. To set the disabled dates, you can use the `DisabledDates` property. + +```ts +let dateRange = document.querySelector('igc-date-range-picker') as IgcDateRangePickerComponent; + +const minDate = new Date(2025, 4, 1); +const maxDate = new Date(2025, 4, 31); + +dateRange.disabledDates = [ + { + type: DateRangeType.Between, + dateRange: [minDate, maxDate] + } +] as DateRangeDescriptor[]; +``` + +You can see more information about all the possibilities that the `DisabledDates` property offers here: [Disabled dates](./calendar.md#disabled-dates) + +You can also do the same if you want to set one or more special dates in the calendar; the only difference is that you need to use the `SpecialDates` property instead. [Special dates](./calendar.md#special-dates) + +### Forms + +The `DateRangePicker` component can also be used seamlessly with the HTML form element. The `Min`, `Max`, and `Required` properties act as form validators. + +`sample="/scheduling/date-range-picker/form", height="500", alt="{Platform} Date Range Picker Form Example"` + +## Additional configuration + +### Properties + +In addition to the properties we've already covered, the `DateRangePicker` component offers a variety of additional properties that allow you to further configure its behavior. + + + +|Name|Type|Description| +|--|--|--| +| `Disabled` | boolean | Disables the component. | +| `NonEditable` | boolean | Disables typing in the input field(s). | +| `Placeholder` | string | Placeholder text for the single input mode. | +| `PlaceholderStart` | string | Placeholder text for the start date input (two inputs mode). | +| `PlaceholderEnd` | string | Placeholder text for the end date input (two inputs mode). | +| `Outlined` | boolean | Determines whether the input part will have outline appearance in the [Material theme](../themes/overview.md). | +| `Prompt` | string | The prompt character used for unfilled parts of the input(s) mask. | +| `ResourceStrings` | IgcDateRangePickerResourceStrings | Resource strings for localization of the date-range picker and the calendar. | + + + +### Slots + +You also have the ability to add custom content and modify the appearance of the `DateRangePicker` component using the available slots. + +The `prefix` and `suffix` slots allow you to insert custom content before or after the input field (only available in single input mode): + +```html + + + + +``` + +In two inputs mode, you can use the `prefix-start`, `prefix-end`, `suffix-start`, and `suffix-end` slots instead to target the individual inputs. + +Another set of useful slots are `clear-icon` and `calendar-icon`, which allow you to customize the icons for the clear and calendar buttons in the input fields: + +```html + + + + +``` + +In two inputs mode, you can also customize the default “to” text between the fields by using the `separator` slot: + +```html + + till + +``` + +The `actions` slot allows you to insert a custom action button with your own logic. For example, the button below toggles week numbers column in the calendar: + +```html + + Toggle Week Numbers + +``` + +In addition to the slots we've already covered, the following slots are also available in the `DateRangePicker` component: + + + +|Name|Description| +|--|--| +| `title` | Renders content for the calendar title. Applicable only in dialog mode. | +| `helper-text` | Renders content below the input field(s). | +| `header-date` | Replaces the default current date/range text in the calendar header. Applicable only in dialog mode. | +| `clear-icon-start` | Custom clear icon for the start input (two inputs mode). | +| `clear-icon-end` | Custom clear icon for the end input (two inputs mode). | +| `calendar-icon-start` | Custom calendar icon for the start input (two inputs mode). | +| `calendar-icon-end` | Custom calendar icon for the end input (two inputs mode). | +| `calendar-icon-open` | Icon or content shown when the picker is open (applies to both inputs in two inputs mode). | +| `calendar-icon-open-start` | Icon or content for the open state of the start input (two inputs mode).| +| `calendar-icon-open-end` | Icon or content for the open state of the end input (two inputs mode). | + + + +`sample="/scheduling/date-range-picker/slots", height="500", alt="{Platform} Date Range Picker Slots Example"` + +### Methods + + + +In addition to the properties and slots, the `DateRangePicker` also exposes few methods that you can use: + +|Name|Description| +|--|--| +| `Show` | Displays the calendar picker component. | +| `Hide` | Hides the calendar picker component. | +| `Toggle` | Toggles the calendar picker between the shown and hidden states. | +| `Clear` | Clears the input fields, removing any user input. | +| `Select` | Selects a date range value in the picker. | +| `SetCustomValidity` | Sets a custom validation message. If the provided message is not empty, the input will be marked as invalid. | + + + +## Styling + +Since the `DateRangePicker` component uses the `Calendar` component, it also inherits the Calendar's CSS parts, allowing you to style both components seamlessly. You can find the full list of exposed Calendar CSS parts here: [Calendar Styling](calendar.md#styling). In addition to the Calendar's CSS parts, the `DateRangePicker` also exposes some unique CSS parts that you can use to customize its appearance: + +|Name|Description| +|--|--| +| `separator` | The separator element between the two inputs. | +| `ranges` | The wrapper that renders the custom and predefined ranges. | +| `label` | The label wrapper that renders content above the target input. | +| `container` | The main wrapper that holds all main input elements. | +| `input` | The native input element. | +| `prefix` | The prefix wrapper. | +| `suffix` | The suffix wrapper. | +| `calendar-icon` | The calendar icon wrapper for the closed state. | +| `calendar-icon-start` | The calendar icon wrapper for the closed state of the start input (two inputs). | +| `calendar-icon-end` | The calendar icon wrapper for the closed state of the end input (two inputs). | +| `calendar-icon-open` | The calendar icon wrapper for the open state. | +| `calendar-icon-open-start` | The calendar icon wrapper for the open state of the start input (two inputs). | +| `calendar-icon-open-end` | The calendar icon wrapper for the open state of the end input (two inputs). | +| `clear-icon` | The clear icon wrapper (single input). | +| `clear-icon-start` | The clear icon wrapper for the start input (two inputs). | +| `clear-icon-end` | The clear icon wrapper for the end input (two inputs). | +| `actions` | The actions wrapper. | +| `helper-text` | The helper-text wrapper that renders content below the target input. | + +```css +igc-date-range-picker::part(label) { + color: var(--ig-gray-600); +} + +igc-date-range-picker::part(calendar-icon-start), +igc-date-range-picker::part(calendar-icon-end) { + background-color: var(--ig-primary-500); + color: var(--ig-primary-500-contrast); +} + +igc-date-range-picker::part(calendar-icon-open-start), +igc-date-range-picker::part(calendar-icon-open-end) { + background-color: var(--ig-primary-700); + color: var(--ig-primary-700-contrast); +} + +igc-date-range-picker::part(clear-icon-start), +igc-date-range-picker::part(clear-icon-end) { + background-color: var(--ig-error-500); + color: var(--ig-error-500-contrast); +} +``` + +`sample="/scheduling/date-range-picker/styling", height="500", alt="{Platform} Date Range Picker Styling Example"` + +## API References + + - `Input` + - `Calendar` + - `DatePicker` + - `DateTimeInput` + - `Dialog` + - [`Styling & Themes`](../themes/overview.md) + + +## Additional Resources + +* [{ProductName} **Forums**]({ForumsLink}) +* [{ProductName} **GitHub**]({GithubLink}) \ No newline at end of file diff --git a/docConfig.json b/docConfig.json index 1f20aa50f..859cb864e 100644 --- a/docConfig.json +++ b/docConfig.json @@ -514,6 +514,7 @@ "ComponentBoolValueChangedEventArgs", "ComponentValueChangedEventArgs", "DatePicker", + "DateRangePicker", "DateRangeType", "DateRangeDescriptor", "DateTimeInputComponent", diff --git a/docfx/en/components/toc.json b/docfx/en/components/toc.json index ed0d9fb15..ab5ef4ddd 100644 --- a/docfx/en/components/toc.json +++ b/docfx/en/components/toc.json @@ -1843,8 +1843,14 @@ "exclude": ["Angular"], "name": "Date Picker", "href": "scheduling/date-picker.md", - "status": "NEW" + "status": "" }, + { + "exclude": ["Angular", "React", "Blazor"], + "name": "Date Range Picker", + "href": "scheduling/date-range-picker.md", + "status": "NEW" + }, { "exclude": ["Angular"], "name": "Styling & Themes",