> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/date-range.md).
# Date Range
`avonni-date-range`
Lets users select a start and end date, and optionally times, to define a range.
## Overview
**Date Range** is a Lightning Web Component that captures a start and end date (optionally with times) through paired inputs and a calendar, with optional predefined range presets.
Use it in your own Lightning Web Components to collect a date or date-time interval such as a booking window, reporting period, or filter range. You control the labels, type, display styles, predefined options, and validation—all through the component's attributes.
### Use Cases
* **Booking windows:** Capture check-in and check-out dates.
* **Reporting periods:** Let users pick a start and end date for a report.
* **Date-time intervals:** Collect both date and time for scheduling.
* **Filter ranges:** Drive list or chart filters with a date range.
* **Preset ranges:** Offer quick options like "This month" or "Last quarter".
***
## Type Guidelines
| Type | Use Case |
| ---------- | --------------------------------------------------------- |
| `date` | Day-level ranges (default), e.g. booking or report dates. |
| `datetime` | Ranges that need a time of day, e.g. scheduling windows. |
***
## Use Case Examples
### Example 1: Booking window with preset ranges
**Scenario:** Capture a stay's check-in and check-out dates with predefined range options and a required validation message.
```html
```
```js
// tripDates.js
import { LightningElement } from 'lwc';
export default class TripDates extends LightningElement {
startDate = '2026-06-15';
endDate = '2026-06-22';
handleChange(event) {
const { startDate, endDate, rangeOptionValue } = event.detail;
// startDate / endDate are ISO8601 strings
}
}
```
**Result:** A start/end date picker with preset range options; changing the range fires `change` with both dates and the selected preset value.
### Example 2: Date-time range
**Scenario:** Capture a booking window that includes both a date and a time for the start and end, displayed with the calendars expanded.
```html
```
```js
// bookingWindow.js
import { LightningElement } from 'lwc';
export default class BookingWindow extends LightningElement {
bookingStart = '2026-07-01T09:00:00.000Z';
bookingEnd = '2026-07-01T17:30:00.000Z';
handleRangeChange(event) {
const { startDate, endDate } = event.detail;
}
}
```
**Result:** A date-time range with separate date and time inputs for each end; changing either value fires `change` with ISO8601 start and end strings.
***
## Specifications
### Attributes
| Name | Description | Type | Default | Required |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------- | -------- |
| `date-style` | The display style of the date. Valid values are short, medium and long. The format of each style is specific to the locale. On mobile devices this attribute has no effect. | String | `"medium"` | |
| `disabled` | If present, the input field is disabled and users cannot interact with it. | Boolean | `false` | |
| `end-date` | Specifies the value of the end date input, which can be a Date object, timestamp, or an ISO8601 formatted string. | (string | Date | number) |
| `field-level-help` | Help text detailing the purpose and function of the input. This attribute isn't supported for file, radio, toggle, and checkbox-button types. | String | — | |
| `is-expanded` | If present, the input is expanded to show the calendars. | Boolean | `false` | |
| `label` | Text label for the input. | String | — | Yes |
| `label-end-date` | Text label for the end input. | String | — | |
| `label-end-time` | If type is datetime, text label for the end time input. | String | — | |
| `label-range-options` | Labels for the range options. This object must be a map where: - the **key** is the range option `value` - the **value** is the label displayed to the user Expected keys: today, yesterday, thisWeek, lastWeek, thisMonth, lastMonth, thisQuarter, lastQuarter, thisYear, lastYear, monthToDate, quarterToDate, yearToDate and custom. Any missing key will fall back to the default label. | Object\ | — | |
| `label-start-date` | Text label for the start input. | String | — | |
| `label-start-time` | If type is datetime, text label for the start time input. | String | — | |
| `message-when-value-missing` | Error message to be displayed when a required date is missing. | String | — | |
| `read-only` | If present, the input is read-only and cannot be edited by users. | Boolean | `false` | |
| `required` | If present, the input field must be filled out before the form is submitted. | Boolean | `false` | |
| `required-alternative-text` | The assistive text when the required attribute is set to true. | String | — | |
| `show-range-options` | If present, a combobox for predefined date ranges is displayed. | Boolean | `false` | |
| `start-date` | Specifies the value of the start date input, which can be a Date object, timestamp, or an ISO8601 formatted string. | (string | Date | number) |
| `time-style` | The display style of the time when type='time' or type='datetime'. Valid values are short, medium and long. Currently, medium and long styles look the same. | String | `"short"` | |
| `timezone` | Time zone used, in a valid IANA format. | String | `"Current user's time zone"` | |
| `today-button-label` | Text label for the today button on the calendar. | String | — | |
| `type` | Valid types include date and datetime. | String | `"date"` | |
| `validity` | Represents the validity states that an element can be in, with respect to constraint validation. | String | — | |
| `value` | Value of the input. The value is read-only. | AvonniInputDateRangeValue | — | |
| `variant` | The variant changes the appearance of an input field. Accepted variants include standard and label-hidden. This value defaults to standard, which displays the label above the field. Use label-hidden to hide the label but make it available to assistive technology. | String | `"standard"` | |
| `week-start-day` | Day displayed as the first day of the week. The value has to be a number between 0 and 6, 0 being Sunday, 1 being Monday, and so on until 6. | Number | `"Current user's locale"` | |
### Methods
| Name | Description | Argument Name | Argument Type | Argument Description |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blur` | Removes keyboard focus from the start date input, end date input and combobox. | | | |
| `checkValidity` | Checks if the input is valid. | | | |
| `focus` | Sets focus on the start date input. | | | |
| `reportValidity` | Displays the error messages. If the input is valid, `reportValidity()` clears displayed error messages. | | | |
| `setCustomValidity` | Sets a custom error message to be displayed when a form is submitted. | `message` | String | The string that describes the error. If message is an empty string, the error message is reset. |
| `setRangeOption` | Sets a predefined range. | `rangeOptionValue` | String | Valid values are are today, yesterday, thisWeek, lastWeek, thisMonth, lastMonth, thisQuarter, lastQuarter, thisYear, lastYear, monthToDate, quarterToDate, yearToDate and custom. |
| | | `applyRange` | Boolean | If present, a range is applied on start and end date and a change event is dispatched. |
| `showHelpMessageIfInvalid` | Displays error messages on invalid fields. An invalid field fails at least one constraint validation and returns false when `checkValidity()` is called. | | | |
### Custom Events
#### `blur`
The event fired when the focus is removed from the input date range.
The `blur` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `change`
The event fired when the value changed.
The `change` event returns the following parameters.
| Parameter | Type | Description |
| ------------------ | ------ | ------------------------------------------- |
| `startDate` | string | Start date, as an ISO8601 formatted string. |
| `endDate` | string | End date, as an ISO8601 formatted string. |
| `rangeOptionValue` | string | The value of the range option. |
The event properties are as follows.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `focus`
The event fired when the focus is set on the input date range.
The `focus` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
### Styling Hooks
| CSS Variable | Type | Default |
| --------------------------------------------------------------------------------------- | --------- | ------------- |
| `--avonni-input-date-range-calendar-color-background` | color | `transparent` |
| `--avonni-input-date-range-calendar-date-text-color` | color | `#080707` |
| `--avonni-input-date-range-calendar-date-disabled-text-color` | color | `#adadad` |
| `--avonni-input-date-range-calendar-weekdays-text-color` | color | `#3e3e3c` |
| `--avonni-input-date-range-calendar-month-text-color` | color | `#080707` |
| `--avonni-input-date-range-calendar-today-color-background` | color | `#ecebea` |
| `--avonni-input-date-range-calendar-today-text-color` | color | `#080707` |
| `--avonni-input-date-range-calendar-date-color-background-hover` | color | `#f3f2f2` |
| `--avonni-input-date-range-calendar-selected-date-color-background` | color | `#0176d3` |
| `--avonni-input-date-range-calendar-selected-date-color-background-focus` | color | `#035d96` |
| `--avonni-input-date-range-calendar-selected-date-color-background-hover` | color | `#0176d3` |
| `--avonni-input-date-range-calendar-selected-date-text-color` | color | `#ffffff` |
| `--avonni-input-date-range-calendar-selected-date-text-color-focus` | color | `#ffffff` |
| `--avonni-input-date-range-calendar-selected-date-text-color-hover` | color | `#ffffff` |
| `--avonni-input-date-range-calendar-multi-selected-color-border-hover` | color | `#d3d3d39a` |
| `--avonni-input-date-range-calendar-multi-selected-styling-border-hover` | styling | `dashed` |
| `--avonni-input-date-range-calendar-week-label-text-color` | color | `#747474` |
| `--avonni-input-date-range-calendar-week-label-font-size` | font | `0.8125em` |
| `--avonni-input-date-range-calendar-week-label-font-weight` | font | `600` |
| `--avonni-input-date-range-expanded-calendar-container-spacing-block-end` | dimension | `0` |
| `--avonni-input-date-range-expanded-calendar-container-spacing-block-start` | dimension | `0` |
| `--avonni-input-date-range-expanded-calendar-container-spacing-inline-end` | dimension | `0` |
| `--avonni-input-date-range-expanded-calendar-container-spacing-inline-start` | dimension | `0` |
| `--avonni-input-date-range-expanded-vertical-navigation-container-spacing-block-end` | dimension | `0` |
| `--avonni-input-date-range-expanded-vertical-navigation-container-spacing-block-start` | dimension | `0` |
| `--avonni-input-date-range-expanded-vertical-navigation-container-spacing-inline-end` | dimension | `0` |
| `--avonni-input-date-range-expanded-vertical-navigation-container-spacing-inline-start` | dimension | `0` |
| `--avonni-input-date-range-header-text-color` | color | `#080707` |
| `--avonni-input-date-range-header-font-size` | font | `0.8125rem` |
| `--avonni-input-date-range-header-font-style` | font | `normal` |
| `--avonni-input-date-range-header-font-weight` | font | `400` |
| `--avonni-input-date-range-labels-text-color` | color | `#3e3e3c` |
| `--avonni-input-date-range-labels-font-size` | font | `0.75rem` |
| `--avonni-input-date-range-labels-font-style` | font | `normal` |
| `--avonni-input-date-range-labels-font-weight` | font | `400` |
## Key Considerations
* **Accessibility:** `label` is required; add `label-start-date` and `label-end-date` so each input is individually labeled.
* **Value is read-only:** Set the range through `start-date` and `end-date` rather than the read-only `value` property, and read updates from the `change` event.
* **Date-time:** Use `type="datetime"` to expose time inputs; provide the time labels so users know what each field controls.
* **Presets:** `show-range-options` adds a combobox of presets; customize the preset labels via `label-range-options`.
* **Best Practice:** Set both `label-start-date` and `label-end-date` so each input is clearly identified, and enable `show-range-options` to give users common presets instead of manual entry.
***
## Troubleshooting Common Issues
* **Range not updating:** Read `event.detail.startDate` and `event.detail.endDate` in the `change` handler; the `value` property is read-only.
* **Time inputs missing:** Confirm `type="datetime"` is set and the time labels are provided.
* **Dates display in the wrong format:** Adjust `date-style` (and `time-style` for date-time) to match the locale-appropriate format you need.
* **If issues persist:** Contact our support team at for assistance.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.avonnicomponents.com/lwc-components/core-components/date-range.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.