> 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-time-picker.md).
# 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.
```html
```
```js
// 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.
```html
```
```js
// 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. |
### 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 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-time-picker.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.