> 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/data-driven-components/scheduler.md).
# Scheduler
`avonni-dd-scheduler`
The Avonni Data Driven Scheduler displays records as events in different variants (timeline, agenda, or calendar).
## Overview
**Scheduler** is a data-driven Lightning Web Component that displays records as events on a schedule, with built-in calendar, agenda, and timeline views, a header with navigation and filters, and interactive item actions.
The scheduler runs in **query mode**: you supply a `query` for the records and a `mapping` that ties record fields to event properties (title, start/end dates, resource, color). Users can switch between the `calendar`, `agenda`, and `timeline` variants, navigate dates, and change the visible time span.
### Use Cases
* **Activity calendars:** Show Events or Tasks on a month/week/day calendar centered on the current date.
* **Resource scheduling:** Group items by a resource (account, owner, equipment) with per-resource colors on a timeline.
* **Field service dispatch:** Drag-edit appointments and create new ones directly on the grid.
* **Team agendas:** Present a scrollable agenda list of upcoming events for a rep or queue.
* **Project timelines:** Use the timeline variant to visualize records across a long horizon with zoom-to-fit.
* **Booking views:** Restrict available days, months, and time frames so users only see schedulable slots.
***
## Use Case Examples
### Example 1: Query mode
**Scenario:** Display standard Activity Events on a calendar, with a header avatar and search, letting users select an event to inspect it.
```html
```
```js
// activityCalendar.js
import { LightningElement } from 'lwc';
export default class ActivityCalendar extends LightningElement {
eventQuery = {
objectApiName: 'Event',
orderBy: 'StartDateTime ASC',
limit: 200
};
// Field values are inserted with the {{Record.FieldApiName}} syntax.
eventMapping = {
title: '{{Record.Subject}}',
name: '{{Record.Id}}',
startDate: '{{Record.StartDateTime}}',
endDate: '{{Record.EndDateTime}}',
allDay: '{{Record.IsAllDayEvent}}'
};
eventSearchFields = ['Subject'];
eventFilters = ['ShowAs', 'IsAllDayEvent'];
headerAvatar = { fallbackIconName: 'standard:event', variant: 'circle' };
handleItemSelect(event) {
const record = event.detail.record; // selected Event SObject
}
handleNavigate(event) {
const date = event.detail.date; // ISO 8601 of the new center date
}
handleFilter(event) {
const value = event.detail.value;
}
handleError(event) {
const message = event.detail.message;
}
}
```
**Result:** A monthly calendar of Activity events centered on today. Users can search by subject, filter by status, switch views, and click an event to fire `itemselect` with the underlying record.
### Example 2: Query mode — resource timeline with drag editing
**Scenario:** Show appointments on a timeline grouped by account resource, with per-resource colors, and allow reps to drag to reschedule.
```html
```
```js
// appointmentTimeline.js
import { LightningElement } from 'lwc';
export default class AppointmentTimeline extends LightningElement {
apptQuery = {
objectApiName: 'Event',
filter: 'WhatId != null',
orderBy: 'StartDateTime ASC',
limit: 300
};
// resourceName maps to the related account; resourceMapping describes how
// to render that related record as a scheduler resource.
apptMapping = {
title: '{{Record.Subject}}',
name: '{{Record.Id}}',
startDate: '{{Record.StartDateTime}}',
endDate: '{{Record.EndDateTime}}',
resourceName: '{{Record.AccountId}}',
resourceMapping: {
label: '{{Record.Name}}',
name: '{{Record.Id}}',
avatarFallbackIconName: 'standard:account'
}
};
timelineAttributes = { editItemOnDrag: true, zoomToFit: true };
palette = ['#8ecae6', '#219ebc', '#023047', '#ffb703', '#fb8500'];
itemActions = [{ name: 'edit', label: 'Edit', iconName: 'utility:edit' }];
handleItemEdit(event) {
const { start, end, record } = event.detail; // changed dates + record
}
handleItemActionClick(event) {
const { name, record } = event.detail;
}
}
```
**Result:** A horizontal timeline grouping appointments by account, each resource in its own palette color. Dragging an item fires `itemedit` with the new `start`/`end`; the item action menu fires `itemactionclick`.
***
## Specifications
### Attributes
| Name | Description | Type | Default | Required |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------- | -------- |
| `available-days-of-the-week` | Array of available days of the week. If present, the scheduler will only show the available days of the week. Defaults to all days being available. The days are represented by a number, starting from 0 for Sunday, and ending with 6 for Saturday. For example, if the available days are Monday to Friday, the value would be: `[1, 2, 3, 4, 5]` | number\[] | `"0, 1, 2, 3, 4, 5, 6"` | |
| `available-months` | Array of available months. If present, the scheduler will only show the available months. Defaults to all months being available. The months are represented by a number, starting from 0 for January, and ending with 11 for December. For example, if the available months are January, February, June, July, August and December, the value would be: `[0, 1, 5, 6, 7, 11]` | number\[] | `"0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11"` | |
| `available-time-frames` | Array of available time frames. If present, the scheduler will only show the available time frames. Defaults to the full day being available. Each time frame string must follow the pattern ‘start-end’, with start and end being ISO 8601 formatted time strings. For example, if the available times are from 10am to 12pm, and 2:30pm to 6:45pm, the value would be: `['10:00-11:59', '14:30-18:44']` | string\[] | `"'00:00-23:59'"` | |
| `empty-spot-actions` | Array of actions. They will be displayed in the scheduler context menu, if there is no item at the clicked position. | DdSchedulerAction\[] | — | |
| `filters` | Array of field API names that belong to the queried object. These fields will be displayed as user filters. | string\[] | — | |
| `filters-attributes` | Object defining the filters-specific attributes. | DdElementFiltersAttributes | — | |
| `header-actions` | Array of actions to display at the top right of the header. On click on a header action, the `headeractionclick` event is fired. | DdElementAction\[] | — | |
| `header-avatar` | Avatar displayed at the top left of the header. | DdElementAvatar | — | |
| `header-help-text` | If present, a help text icon is displayed next to the header title. On focus or hover on the icon, the header help text is displayed in a tooltip. | String | — | |
| `header-help-text-attributes` | Object defining the help text-specific attributes. | DdElementHelpTextAttributes | — | |
| `header-show-time-zone` | If present, a time zone picker will be displayed in the header. | Boolean | `false` | |
| `header-title` | Main title displayed in the header. | String | — | |
| `header-visible-actions-count` | Number of header actions that appear as regular buttons. Remaining actions appear in a dropdown menu. | integer | — | |
| `hidden-variants` | Array of variants that cannot be selected by the user. Defaults to all variants being available. The variants values are agenda, calendar, and timeline. | string\[] | — | |
| `hide-header` | If present, the header is hidden. | Boolean | `false` | |
| `item-actions` | Array of actions. They will be displayed in the context menu and in the detail popover of an item. | DdSchedulerAction\[] | — | |
| `item-palette` | Array of valid CSS color strings. They will be used as a default palette for the items that do not have a specific color assigned through their mapping. Each resource will be assigned a color, and the items that belong to that resource will be displayed in that color. If there are more resources than colors in the palette, the colors will be repeated. | string\[] | — | |
| `item-popover-fields` | Array of fields that will be displayed in the popover visible on hover on an item. If not provided, the start and end dates of the items are displayed. | DdSchedulerItemPopoverField\[] | — | |
| `item-theme` | Styling theme of the items. Valid values include default, transparent, line, hollow, and rounded. | String | `"default"` | |
| `label-no-items-found` | Label of the message displayed when there are no items found. | String | `"No events for the selected date."` | |
| `label-today-button` | Label of the button displayed in the header, that navigates to the current date. | String | `"Today"` | |
| `mapping` | Object defining the way the records returned by the query should be mapped to the scheduler item properties. To insert the value of a field, use the syntax `{{Record.FieldApiName}}`. For example, to use the value of the Subject field, use `{{Record.Subject}}`. | DdSchedulerMapping | — | |
| `query` | Definition of the query to execute to get the records that will be mapped. | DdElementQuery | — | |
| `refresh-emp` | Object describing a platform event that should be subscribed to in order to refresh the component when an event is published. | DdElementRefreshEmp | — | |
| `search-attributes` | Object defining the search-specific attributes. | DdElementSearchAttributes | — | |
| `search-fields` | Array of field API names that can be used by the search box to filter the records. The fields must belong to the queried object, and they must be filterable. | string\[] | — | |
| `selected-date` | Selected date of the scheduler, represented as an ISO 8601 formatted string. The scheduler will be centered on this date. If no date is selected, the scheduler will be centered on the current date. | String | — | |
| `selected-time-span-name` | Name of the selected time span. If `time-spans` are provided, the value should match one of the given time span names. Otherwise, it should match one of the default names: `Standard.Scheduler.DayTimeSpan`, `Standard.Scheduler.WeekTimeSpan`, or `Standard.Scheduler.MonthTimeSpan`. If not provided, the first time span of the list will be selected. | String | — | |
| `side-panel-attributes` | Object defining the side panel-specific attributes. | DdElementSidePanelAttributes | — | |
| `time-spans` | Array of available time spans. The time spans can be selected by the user in the header and define the visible duration of the scheduler. | DdSchedulerTimeSpan\[] | — | |
| `variant` | Selected variant of the scheduler. Valid values include agenda, calendar, and timeline. | String | `"calendar"` | |
| `variant-attributes` | Object defining variant-specific attributes. | DdSchedulerVariantAttributes | — | |
| `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. If it is not provided, the user locale will be used. | Number | — | |
### Mapping
The `mapping` object ties queried record fields to scheduler event properties. Insert a field value with the `{{Record.FieldApiName}}` syntax (e.g. `{{Record.Subject}}`).
| Mapping Key | Type | Description |
| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | String | Event title. e.g. `'{{Record.Subject}}'`. |
| `name` | String | Unique item name. Defaults to the `Id` field. |
| `startDate` | Date | Event start. e.g. `'{{Record.StartDateTime}}'`. |
| `endDate` | Date | Event end. e.g. `'{{Record.EndDateTime}}'`. |
| `allDay` | Boolean | Whether the event is all-day. e.g. `'{{Record.IsAllDayEvent}}'`. |
| `color` | String | Item color. Defaults to the resource color. |
| `theme` | String | Item theme. Defaults to the scheduler's `item-theme`. |
| `resourceName` | String | Unique name of the resource the item belongs to. e.g. `'{{Record.AccountId}}'`. |
| `resourceMapping` | Object | Used when `resourceName` maps to a relationship field. Maps the related record with `{ label, name, avatarFallbackIconName, avatarInitials, avatarSrc }`, where `{{Record.Field}}` refers to the **related** record. |
### Methods
| Name | Description | Argument Name | Argument Type | Argument Description |
| --------- | ------------------------------------------------------------- | ------------------- | ------------- | ----------------------------------------------------------------- |
| `refresh` | Refresh the query and the records displayed in the component. | `stayOnCurrentPage` | Boolean | If true, the component will refresh but stay on the current page. |
### Custom Events
#### `emptyspotactionclick`
Event fired when an empty spot action is clicked.
The `emptyspotactionclick` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------ |
| `from` | string | Start date of the cell clicked, as an ISO 8601 string. |
| `name` | string | Name of the action clicked. |
| `to` | string | End date of the cell clicked, as an ISO 8601 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. |
#### `error`
The event fired when an error occurs in the component.
The `error` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | --------------------- |
| `message` | string | Message of the error. |
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. |
#### `filter`
The event fired when the user filters the records.
The `filter` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | object | Object containing the filters applied by the user. Its keys correspond to the field API names of the selected filters. The values are arrays of strings, corresponding to the values selected for the filter. |
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. |
#### `headeractionclick`
The event fired when a header action is clicked.
The `headeractionclick` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | --------------------------- |
| `name` | string | Name of the action clicked. |
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. |
#### `itemactionclick`
Event fired when an item action is clicked.
The `itemactionclick` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------------- |
| `name` | string | Name of the action clicked. |
| `record` | object | Record of the item the action belongs to. |
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. |
#### `itemedit`
Event fired when an item is edited.
The `itemedit` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `end` | string | End date of the item, as an ISO 8601 string. Present only if the end date of the item has changed. |
| `record` | object | Record of the item that was edited. |
| `start` | string | Start date of the item, as an ISO 8601 string. Present only if the start date of the item has changed. |
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. |
#### `itemselect`
Event fired when an item is selected.
The `itemselect` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------- |
| `record` | object | Record of the item that was selected. |
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. |
#### `navigate`
Event fired when the user navigates to a new date.
The `navigate` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------- |
| `date` | string | Selected date, as an ISO 8601 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. |
#### `nbitemschange`
The event fired when the number of items displayed in the component changes.
The `nbitemschange` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------- | ------------------------------------------- |
| `value` | integer | Number of items displayed in the component. |
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. |
#### `newitem`
Event fired when a new item is created.
The `newitem` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------------------------- |
| `end` | string | End date of the new item, as an ISO 8601 string. |
| `start` | string | Start date of the new item, as an ISO 8601 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. |
#### `timespanselect`
Event fired when the user selects a time span.
The `timespanselect` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------- |
| `name` | string | Name of the selected time span. |
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. |
#### `variantselect`
Event fired when the user selects a variant.
The `variantselect` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------- |
| `name` | string | Name of the selected variant. |
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-dd-scheduler-header-actions-color-background` | color | — |
| `--avonni-dd-scheduler-header-actions-color-background-active` | color | — |
| `--avonni-dd-scheduler-header-actions-color-background-hover` | color | — |
| `--avonni-dd-scheduler-header-actions-color-border` | color | — |
| `--avonni-dd-scheduler-header-actions-color-border-active` | color | — |
| `--avonni-dd-scheduler-header-actions-color-border-hover` | color | — |
| `--avonni-dd-scheduler-header-actions-text-color` | color | — |
| `--avonni-dd-scheduler-header-actions-text-color-active` | color | — |
| `--avonni-dd-scheduler-header-actions-text-color-hover` | color | — |
| `--avonni-dd-scheduler-header-caption-font-family` | string | — |
| `--avonni-dd-scheduler-header-caption-font-size` | dimension | — |
| `--avonni-dd-scheduler-header-caption-font-style` | string | `normal` |
| `--avonni-dd-scheduler-header-caption-font-weight` | number | `400` |
| `--avonni-dd-scheduler-header-caption-letter-spacing` | string | — |
| `--avonni-dd-scheduler-header-caption-line-height` | string | — |
| `--avonni-dd-scheduler-header-caption-text-color` | color | `#000000` |
| `--avonni-dd-scheduler-header-color-background` | color | — |
| `--avonni-dd-scheduler-header-color-border` | color | — |
| `--avonni-dd-scheduler-header-color-border-bottom` | color | `#c9c9c9` |
| `--avonni-dd-scheduler-header-icon-color-background` | color | — |
| `--avonni-dd-scheduler-header-icon-color-foreground` | color | — |
| `--avonni-dd-scheduler-header-icon-color-foreground-default` | color | — |
| `--avonni-dd-scheduler-header-icon-radius-border` | string | — |
| `--avonni-dd-scheduler-header-margin-block-end` | dimension | — |
| `--avonni-dd-scheduler-header-radius-border` | string | — |
| `--avonni-dd-scheduler-header-sizing-border` | string | — |
| `--avonni-dd-scheduler-header-sizing-border-bottom` | dimension | `1px` |
| `--avonni-dd-scheduler-header-spacing-block-end` | dimension | `0.75rem` |
| `--avonni-dd-scheduler-header-spacing-block-start` | dimension | `0.75rem` |
| `--avonni-dd-scheduler-header-spacing-inline-end` | dimension | `1rem` |
| `--avonni-dd-scheduler-header-spacing-inline-start` | dimension | `1rem` |
| `--avonni-dd-scheduler-header-styling-border` | string | — |
| `--avonni-dd-scheduler-header-styling-border-bottom` | string | `solid` |
| `--avonni-dd-scheduler-header-title-font-family` | string | — |
| `--avonni-dd-scheduler-header-title-font-size` | dimension | `1rem` |
| `--avonni-dd-scheduler-header-title-font-style` | string | `normal` |
| `--avonni-dd-scheduler-header-title-font-weight` | number | `400` |
| `--avonni-dd-scheduler-header-title-letter-spacing` | string | — |
| `--avonni-dd-scheduler-header-title-line-height` | number | `1.25` |
| `--avonni-dd-scheduler-header-title-text-color` | color | `#080707` |
## Key Considerations
* **Query-only:** The scheduler has no static `items` input—it always reads records through `query` + `mapping`.
* **Required mapping fields:** Map `title`, `startDate`, and `endDate` so events render and position correctly; `name` defaults to the `Id` field.
* **Date types:** `startDate`/`endDate` should map to date or datetime fields (e.g. `StartDateTime`). All-day events come from a boolean field via `allDay`.
* **Resources:** Use `resourceName` with `resourceMapping` to group items by a related record, and `item-palette` to color them per resource.
* **Availability constraints:** `available-days-of-the-week`, `available-months`, and `available-time-frames` restrict what the user can see and schedule.
* **Best Practice:** Always map `title`, `startDate`, and `endDate` so each event renders with a label and a position on the schedule. Use `item-palette` and a `resourceName` mapping when you want events visually grouped by resource.
***
## Troubleshooting Common Issues
* **No events appear:** Verify `query.objectApiName` and that `startDate`/`endDate` map to real date fields; events outside `selected-date`'s visible range, days, months, or time frames are hidden.
* **Items all the same color:** Without a `color` mapping or a `resourceName`, the `item-palette` cannot vary by resource—add a `resourceName` mapping.
* **Drag editing does nothing:** `editItemOnDrag` (and `createItemOnDrag`) must be set in `variant-attributes`, and these apply only to the calendar and timeline variants.
* **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/data-driven-components/scheduler.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.