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.

<!-- tripDates.html -->
<template>
    <avonni-date-range
        label="Trip dates"
        field-level-help="Pick the first and last day of your stay."
        label-start-date="Check in"
        label-end-date="Check out"
        start-date={startDate}
        end-date={endDate}
        date-style="medium"
        today-button-label="Today"
        show-range-options
        required
        message-when-value-missing="Both a start and end date are required."
        onchange={handleChange}
    ></avonni-date-range>
</template>

// 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.

<!-- bookingWindow.html -->
<template>
    <avonni-date-range
        label="Booking window (with time)"
        label-start-date="From"
        label-start-time="Start time"
        label-end-date="To"
        label-end-time="End time"
        type="datetime"
        date-style="long"
        time-style="short"
        start-date={bookingStart}
        end-date={bookingEnd}
        is-expanded
        onchange={handleRangeChange}
    ></avonni-date-range>
</template>

// 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<string, string>	—
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	—
orientation	Orientation of the calendar. Valid values include horizontal and vertical. Supported only when is-expanded is true.	String	"horizontal"
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-step-minutes	Specifies the time interval in minutes for the time inputs dropdown options. Any positive integer above or equal to 5 is valid.	Number	15
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.

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 [email protected] for assistance.