Date Picker

avonni-date-picker

Lets users select a date from a calendar interface, with support for date ranges and disabled dates.

Overview

Date Picker is a Lightning Web Component that displays an interactive calendar for selecting a single date, multiple dates, or a date interval.

Use it in your own Lightning Web Components to capture date selections with rich calendar features such as disabled dates, marked dates, date labels, and multi-month views. You control the selection mode, min/max range, navigation, and visual markers—all through the component's attributes.

Use Cases

• Single date selection: Pick a due date or appointment day.
• Date ranges: Select a start and end date in interval mode.
• Multi-date selection: Choose several non-contiguous dates.
• Availability calendars: Disable unavailable dates and mark key days.
• Event highlighting: Add labels and color markers to milestone dates.

---

Selection Mode Guidelines

Mode	Use Case
single	One date at a time (default); value is a string.
multiple	Several non-contiguous dates; value is an array.
interval	A start/end date range (two dates); value is an array.

---

Use Case Examples

Example 1: Date range with disabled and marked dates

Scenario: Let users select a date interval across two months, blocking certain dates and highlighting milestones with color markers and labels.

<!-- bookingCalendar.html -->
<template>
    <avonni-date-picker
        selection-mode="interval"
        nb-month-calendars="2"
        min={minDate}
        max={maxDate}
        value={selectedRange}
        disabled-dates={disabledDates}
        marked-dates={markedDates}
        date-labels={dateLabels}
        show-week-number
        onchange={handleChange}
    ></avonni-date-picker>
</template>

// bookingCalendar.js
import { LightningElement } from 'lwc';

export default class BookingCalendar extends LightningElement {
    minDate = '2024-01-01';
    maxDate = '2024-12-31';
    selectedRange = ['2024-06-10', '2024-06-14'];
    disabledDates = ['2024-06-08', '2024-06-09'];
    markedDates = [{ date: '2024-06-12', color: '#0176d3' }];
    dateLabels = [
        { date: '2024-06-12', label: 'Kickoff', variant: 'brand', iconName: 'utility:event' }
    ];

    handleChange(event) {
        const value = event.detail.value;       // ['2024-06-10', '2024-06-14']
        const clicked = event.detail.clickedDate; // last clicked date
    }
}

Result: A two-month calendar with a selected range, disabled days, color markers, and labels; changing the selection fires change with the date array.

Example 2: Single-date selection

Scenario: Capture a single due date within an allowed range.

<!-- dueDate.html -->
<template>
    <avonni-date-picker
        selection-mode="single"
        min="2024-01-01"
        max="2024-12-31"
        value={dueDate}
        onchange={handleChange}
    ></avonni-date-picker>
</template>

// dueDate.js
import { LightningElement } from 'lwc';

export default class DueDate extends LightningElement {
    dueDate = '2024-06-15';

    handleChange(event) {
        this.dueDate = event.detail.value; // ISO8601 string in single mode
    }
}

Result: A single-month calendar; selecting a date fires change with the chosen ISO8601 string.

---

Specifications

Attributes

Name	Description	Type	Default	Required
date-labels	Array of date label objects. If a date has several labels, the first one in the array will be used.	AvonniCalendarDateLabel[]	—
disabled	If true, the calendar is disabled.	Boolean	false
disabled-dates	Array of disabled dates. The dates should be a Date object, a timestamp, or an ISO8601 formatted string.	string[]	—
hide-navigation	Specifies if the calendar header should be hidden.	Boolean	false
marked-dates	Array of marked date objects. A maximum of three markers can be displayed on a same date.	AvonniCalendarMarkedDate[]	—
max	Specifies the maximum date, which the calendar can show.	Date	string	"Date(2099, 11, 31)"
min	Specifies the minimum date, which the calendar can show.	Date	string	"Date(1900, 0, 1)"
nb-month-calendars	Number of month calendars to be displayed.	Number	1
next-month-button-alternative-text	The alternative text for the next month button.	String	—
orientation	Orientation of the calendar. Valid values include horizontal and vertical.	String	"horizontal"
previous-month-button-alternative-text	The alternative text for the previous month button.	String	—
selection-mode	Specifies the selection mode of the calendar. Valid values include single, multiple and interval. If single, only one date can be selected at a time. If multiple, the user can select multiple dates. If interval, the user can only select a date range (two dates).	String	"single"
show-week-number	If present, the week number column will be displayed.	Boolean	false
timezone	Time zone used, in a valid IANA format.	String	"Current user's time zone"
value	The value of the selected date(s). Dates can be a Date object, timestamp, or an ISO8601 formatted string.	string	string[]	—
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"
year-select-assistive-text	The assistive text for the year select.	String	—

Methods

Name	Description	Argument Name	Argument Type	Argument Description
focus	Set the focus on the first focusable element of the calendar.
focusDate	Set the focus on a given date.	date	Date	A value to be focused, which can be a Date object, timestamp, or an ISO8601 formatted string.
goToDate	Move the position of the calendar so the specified date is visible.	date	string	number
nextMonth	Simulates a click on the next month button
previousMonth	Simulates a click on the previous month button

Custom Events

blur

The event fired when the focus is removed from the calendar.

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 selected date is changed.

The change event returns the following parameters.

Parameter	Type	Description
bounds	DOMRect	The size and position of the clicked date in the viewport.
value	string	string[]
clickedDate	string	Clicked date, as an ISO8601 formatted string.

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

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.

navigate

The event fired when the month is changed.

The navigate event returns the following parameters.

Parameter	Type	Description
date	string	First day of the new visible month, as an ISO8601 formatted string.

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.

blur

The event fired when the focus is removed from the calendar.

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 selected date is changed.

The change event returns the following parameters.

Parameter	Type	Description
bounds	DOMRect	The size and position of the clicked date in the viewport.
value	string	string[]
clickedDate	string	Clicked date, as an ISO8601 formatted string.

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

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.

navigate

The event fired when the month is changed.

The navigate event returns the following parameters.

Parameter	Type	Description
date	string	First day of the new visible month, as an ISO8601 formatted string.

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.

Styling Hooks

CSS Variable	Type	Default
--avonni-calendar-color-background	color	transparent
--avonni-calendar-date-text-color	color	#080707
--avonni-calendar-date-disabled-text-color	color	#adadad
--avonni-calendar-weekdays-text-color	color	#3e3e3c
--avonni-calendar-month-text-color	color	#080707
--avonni-calendar-today-color-background	color	#ecebea
--avonni-calendar-today-text-color	color	#080707
--avonni-calendar-date-color-background-hover	color	#f3f2f2
--avonni-calendar-selected-date-color-background	color	#0176d3
--avonni-calendar-selected-date-color-background-focus	color	#035d96
--avonni-calendar-selected-date-color-background-hover	color	#0176d3
--avonni-calendar-selected-date-text-color	color	#ffffff
--avonni-calendar-selected-date-text-color-focus	color	#ffffff
--avonni-calendar-selected-date-text-color-hover	color	#ffffff
--avonni-calendar-multi-selected-color-border-hover	color	#d3d3d39a
--avonni-calendar-multi-selected-styling-border-hover	styling	dashed
--avonni-calendar-week-label-text-color	color	#747474
--avonni-calendar-week-label-font-size	font	0.8125em
--avonni-calendar-week-label-font-weight	font	600
--avonni-calendar-width	dimension	fit-content

Key Considerations

• Value shape: value and the change detail are a string in single mode and an array in multiple and interval modes.
• Disabled dates: Pass ISO8601 strings, timestamps, or Date objects in disabled-dates to prevent selection.
• Markers vs labels: marked-dates adds up to three color dots per date; date-labels adds a labeled badge (the first label wins if multiple apply).
• Time zones: Set timezone explicitly when dates must render consistently regardless of the viewer's locale.
• Best Practice: Set min and max to constrain navigation, and use disabled-dates to prevent selection of unavailable days rather than relying on validation after the fact.

---

Troubleshooting Common Issues

• Selection won't update: Confirm the change handler reads event.detail.value and that you handle the array vs string shape per selection-mode.
• A date can't be selected: Check that it isn't listed in disabled-dates or outside the min/max range.
• Markers not appearing: Each marked-dates entry needs a valid date and color; only three markers render per date.
• If issues persist: Contact our support team at [email protected] for assistance.