Date Time Picker

avonni-date-time-picker

Lets users select one or more date and time slots from a set of available options.

Overview

Date Time Picker is a Lightning Web Component that presents available time slots within a date or date range and lets users pick one (or several) of them.

Use it in your own Lightning Web Components for scheduling and booking flows. You control the visible time window, slot duration, layout variant, navigation, and formatting—all through the component's attributes—and you read the selection from the change event.

Use Cases

• Appointment booking: Let users reserve a 30-minute discovery call.
• Resource scheduling: Offer bookable slots for rooms, equipment, or staff.
• Weekly availability: Show a full week of slots with the weekly variant.
• Multi-slot selection: Use type="checkbox" to let users pick several slots.
• Constrained ranges: Block out unavailable days with disabled-date-times.

---

Variant Guidelines

Variant	Use Case
daily	Default; one day of slots at a time.
weekly	A full week of availability side by side.
monthly	Month overview with a date picker.
inline	Compact embedding inside a form.
timeline	A continuous timeline of slots.

---

Use Case Examples

Example 1: Weekly booking with 30-minute slots

Scenario: Let a prospect book a discovery call from a week of available 30-minute slots, with certain days blocked out.

<!-- bookingPicker.html -->
<template>
    <avonni-date-time-picker
        label="Book a discovery call"
        name="discovery-call"
        variant="weekly"
        type="radio"
        start-time="09:00"
        end-time="12:00"
        time-slot-duration="00:30"
        time-format-hour12
        show-end-time
        field-level-help="Pick an available 30-minute slot."
        disabled-date-times={disabledDateTimes}
        required
        onchange={handleChange}
        onnavigate={handleNavigate}
    ></avonni-date-time-picker>
</template>

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

export default class BookingPicker extends LightningElement {
    disabledDateTimes = ['2024-06-12', '2024-06-13', '2024-06-14'];

    handleChange(event) {
        const value = event.detail.value; // selected slot
        const name = event.detail.name; // 'discovery-call'
    }

    handleNavigate(event) {
        const firstVisibleDay = event.detail.date; // ISO8601
    }
}

Result: A weekly grid of 30-minute slots from 9:00 AM to 12:00 PM, with three days blocked; selecting a slot fires change with the chosen value.

Example 2: Multi-slot daily picker

Scenario: Let a user reserve several slots in a single day for a training session.

<!-- multiSlotPicker.html -->
<template>
    <avonni-date-time-picker
        label="Select training sessions"
        variant="daily"
        type="checkbox"
        start-time="08:00"
        end-time="18:00"
        time-slot-duration="01:00"
        onchange={handleChange}
    ></avonni-date-time-picker>
</template>

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

export default class MultiSlotPicker extends LightningElement {
    handleChange(event) {
        const selectedSlots = event.detail.value; // array of values
    }
}

Result: A daily list of one-hour slots where the user can check multiple slots; change returns an array of the selected values.

---

Specifications

Attributes

Name	Description	Type	Default	Required
avatar	Avatar object. The avatar will be displayed in the header, to the left of the label.	AvonniDateTimePickerAvatar	—
date-format-day	Valid values include numeric and 2-digit.	String	"numeric"
date-format-month	Valid values are numeric, 2-digit, long, short or narrow.	String	"long"
date-format-weekday	Specifies how to display the day of the week. Valid values are narrow, short, or long.	String	"short"
date-format-year	Valid values include numeric and 2-digit.	String	—
date-picker-variant	Variant of the date picker displayed in the header. Valid values include input and inline.	String	"input"
disabled	If present, the date time picker is disabled and users cannot interact with it.	Boolean	false
disabled-date-times	Array of disabled dates. The dates must be Date objects or valid ISO8601 strings.	Date[]	—
display-next-button	If present, display a next button after selecting a time slot.	Boolean	false
end-time	End of the time slots. Must be an ISO8601 formatted time string.	String	"18:00"
field-level-help	Help text detailing the purpose and function of the input.	String	—
hide-date-label	If present, hide the currently visible date or date range.	Boolean	false
hide-date-picker	If present, hide the date picker button.	Boolean	false
hide-label	If present, hides the label.	Boolean	false
hide-navigation	If present, hide next, previous and today buttons.	Boolean	false
label	Text label for the input.	String	—	Yes
max	Maximum date the calendar can show. The value should be a Date object, a timestamp, or an ISO8601 formatted string.	Date	string	"2099-12-31"
message-when-value-missing	Error message to be displayed when the value is missing. The valueMissing error can be returned when you specify the required attribute for any input type.	String	—
min	Minimum date the calendar can show. The value should be a Date object, a timestamp, or an ISO8601 formatted string.	Date	string	"1900-01-01"
name	Specifies the name of an input element.	String	—
next-button-label	Label for the next button.	String	"Next"
next-dates-button-alternative-text	Alternative text for the next dates button.	String	"Next dates"
next-week-button-alternative-text	Alternative text for the next week button.	String	"Next week"
no-results-message	Message to be displayed when there are no available time slots for the selected period.	String	"No available time slots for this period."
previous-dates-button-alternative-text	Alternative text for the previous dates button.	String	"Previous dates"
previous-week-button-alternative-text	Alternative text for the previous week button.	String	"Previous week"
read-only	If present, the input field 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	"Required"
show-disabled-dates	If present, show the disabled dates in the date time picker. Ex: 1:00 PM - 1:30 PM.	Boolean	—
show-end-time	If present, show the end time in each slots. Ex: 1:00 PM - 1:30 PM.	Boolean	—
show-time-zone	If present, show the time zone.	Boolean	false
start-time	Start of the time slots. Must be an ISO8601 formatted time string.	String	"08:00"
time-format-hour	Valid values include numeric and 2-digit.	String	"numeric"
time-format-hour12	Determines whether time is displayed as 12-hour. If false, time displays as 24-hour. The default setting is determined by the user's locale.	Boolean	—
time-format-minute	Valid values include numeric and 2-digit.	String	"2-digit"
time-format-second	Valid values include numeric and 2-digit.	String	—
time-slot-duration	Duration of each time slot. Must be an ISO8601 formatted time string.	String	"00:30"
timezone	Time zone used, in a valid IANA format.	String	"Current user's time zone"
timezone-label	The label for the time zone.	String	"Time Zone:"
timezone-placeholder	The placeholder for the time zone combobox.	String	"Select time zone"
today-button-label	The label for the today button.	String	"Today"
type	Valid values include radio and checkbox.	String	"radio"
validity	Represents the validity states that an element can be in, with respect to constraint validation.	String	—
value	The value of the date selected, which can be a Date object, timestamp, or an ISO8601 formatted string.	String	—
variant	The variant changes the appearance of the time picker. Accepted variants include daily, weekly, monthly, inline and timeline.	String	"daily"
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
checkValidity	Checks if the input is valid.
focus	Set the focus on the date time picker.
getDateRangeBounds	Return the position of the date range label.
goToDate	Move the position of the picker so the specified date is visible.	date	(string	number
		disableRender	Boolean	If present, the picker is rendered again.
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.
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 date time picker.

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
value	string	string[]
name	string	Name of the picker.

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 date time picker.

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 user navigates to another period of time.

The navigate event returns the following parameters.

Parameter	Type	Description
date	string	First visible day, 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.

nextbuttonclick

The event fired when the user clicks on the next button of a selected time slot.

The nextbuttonclick event doesn't return any parameters.

Property	Value	Description
bubbles	true	This event bubbles up through the DOM.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	true	This event propagates outside of the component in which it was dispatched.

blur

The event fired when the focus is removed from the date time picker.

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
value	string	string[]
name	string	Name of the picker.

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 date time picker.

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 user navigates to another period of time.

The navigate event returns the following parameters.

Parameter	Type	Description
date	string	First visible day, 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.

nextbuttonclick

The event fired when the user clicks on the next button of a selected time slot.

The nextbuttonclick event doesn't return any parameters.

Property	Value	Description
bubbles	true	This event bubbles up through the DOM.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	true	This event propagates outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-date-time-picker-button-color-background	color	#ffffff
--avonni-date-time-picker-button-color-background-disabled	color	#f3f2f2
--avonni-date-time-picker-button-color-background-selected	color	#d8edff
--avonni-date-time-picker-button-color-border	color	#dddbda
--avonni-date-time-picker-button-color-border-selected	color	#0070d2
--avonni-date-time-picker-button-sizing-border	dimension	1px
--avonni-date-time-picker-button-sizing-border-selected	dimension	1px
--avonni-date-time-picker-button-styling-border	keyword	solid
--avonni-date-time-picker-button-styling-border-selected	keyword	solid
--avonni-date-time-picker-button-text-color	color	#181818
--avonni-date-time-picker-button-text-color-selected	color	#181818
--avonni-date-time-picker-button-text-color-disabled	color	#706e6b
--avonni-date-time-picker-date-label-line-height	number	1.25
--avonni-date-time-picker-date-label-font-size	dimension	1.25rem
--avonni-date-time-picker-date-label-font-weight	integer	400
--avonni-date-time-picker-date-picker-button-color-background-hover	color	#f3f3f3
--avonni-date-time-picker-date-picker-button-color-background-selected	color	#032d60
--avonni-date-time-picker-date-picker-button-text-color-hover	color	#181818
--avonni-date-time-picker-date-picker-button-text-color-selected	color	#ffffff
--avonni-date-time-picker-label-font-size	dimension	0.75rem
--avonni-date-time-picker-label-font-style	keyword	normal
--avonni-date-time-picker-label-font-weight	integer	700
--avonni-date-time-picker-label-horizontal-alignment	alignment	left
--avonni-date-time-picker-label-line-height	number	1.5
--avonni-date-time-picker-label-text-color	color	#444444
--avonni-date-time-picker-weekly-day-header-text-color	color	#706e6b
--avonni-date-time-picker-weekly-day-header-text-color-today	color	#1589ee
--avonni-date-time-picker-button-radius-border	dimension	0.25rem
--avonni-date-time-picker-button-text-color-hover	color	#014486
--avonni-date-time-picker-color-background	color	#f3f3f3
--avonni-date-time-picker-next-button-color-background	color	#0176d3
--avonni-date-time-picker-next-button-color-background-active	color	#014486
--avonni-date-time-picker-next-button-color-background-hover	color	#014486
--avonni-date-time-picker-next-button-color-border	color	#0176d3
--avonni-date-time-picker-next-button-color-border-active	color	#014486
--avonni-date-time-picker-next-button-color-border-hover	color	#014486
--avonni-date-time-picker-next-button-radius-border	dimension	0.25rem
--avonni-date-time-picker-next-button-sizing-border	sizing	1px
--avonni-date-time-picker-next-button-text-color	color	#ffffff
--avonni-date-time-picker-next-button-text-color-active	color	#ffffff
--avonni-date-time-picker-next-button-text-color-hover	color	#ffffff

Key Considerations

• Required label: label is required—use hide-label to hide it visually while keeping it for assistive technology.
• Slot math: Slots are generated from start-time, end-time, and time-slot-duration; mismatched values can leave partial or empty windows.
• Selection type: change returns a string for radio and an array for checkbox.
• Disabled dates: disabled-date-times accepts Date objects or ISO8601 strings; pair with show-disabled-dates to keep slots visible but unselectable.
• Time zones: Set timezone (IANA format) and show-time-zone for cross-region scheduling.
• Best Practice: Always set label, and align start-time, end-time, and time-slot-duration so the window divides evenly into slots.

---

Troubleshooting Common Issues

• No slots appear: Verify start-time is before end-time and that time-slot-duration divides the window; also check for a noResultsMessage.
• Selection not captured: Confirm the onchange handler is wired and read event.detail.value (an array when type="checkbox").
• Wrong time format: Set time-format-hour12 explicitly; otherwise it follows the user's locale.
• If issues persist: Contact our support team at [email protected] for assistance.