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