> 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/dynamic-components/components/calendar.md).

# Calendar

The Avonni Calendar is a full scheduling application that displays and manages resources and events in multiple formats: Timeline, Calendar, and Agenda. Use it to visualize bookings, assignments, or any time-based data across people, rooms, or equipment.

## Overview

The Avonni Calendar uses two core concepts: **Resources** and **Events**.

* **Resources:** The "who" or "what" of your schedule. Think of these as the people, places, or things being scheduled.
  * *Examples:* Meeting rooms (Room A, Room B), staff members (John Doe, Jane Smith), equipment (Projector, Laptop).
  * *Purpose:* Track availability and prevent scheduling conflicts.
* **Events:** The "when" and "what's happening" of your schedule. These are the scheduled activities.
  * *Examples:* "Team Meeting," "Client Call," "Project Deadline."
  * *Purpose:* Represent scheduled appointments, tasks, or deadlines, typically linked to a specific resource.

**In essence, events are scheduled for resources**. You need to define both to populate your calendar. The next step is to connect these concepts to a data source.

## Configuration

To configure the Calendar, select it on the canvas. The **Edit Calendar** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab.

### Data Source

Before you build your calendar, you must tell it where to get the data it should display. You have several options, depending on the source and nature of your data:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Manual</strong></td><td>Enter data directly into the component configuration.</td><td></td></tr><tr><td><strong>Variable</strong></td><td>This is useful for data that changes based on user interactions or other component logic.</td><td></td></tr><tr><td><strong>Query</strong></td><td>This is the most common option for displaying Salesforce records.</td><td></td></tr></tbody></table>

### Data Mappings

When using a dynamic data source, you'll need to configure the **Data Mappings** section to tell the component how to map your Salesforce records to calendar events and resources.

**Why are Data Mappings Important?**

Without data mapping, the calendar wouldn't know which part of your data to use, resulting in incorrect or irrelevant information.

**How Data Mapping Works**

Data mapping is a translation process where you specify which Salesforce field corresponds to each calendar attribute. Particular attention should be given to the **Resource Names** mapping in the events section — this attribute is crucial because it links each event to its corresponding resource.

* **With Resource Names Mapping**: If an event titled 'Team Meeting' is mapped to 'Room A', it will appear under 'Room A' in the calendar. Similarly, an event 'Client Presentation' mapped to 'Room B' will be displayed under 'Room B'.
* **Without Resource Names Mapping**: If the resource name isn't mapped, all events will appear under a single, undefined resource.

<figure><img src="/files/q4aWGgPkWD8uRlZosf6X" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/QhEssOcW5HxBxPhSkeFu" alt="" width="320"><figcaption></figcaption></figure>

After completing the data mappings, the Avonni Calendar will be ready to visually represent your Salesforce data in the chosen display format.

### Content

The **Content** section controls the display format, time scope, and calendar behavior.

<figure><img src="/files/4VDKieq76BGjevNPXDpB" alt=""><figcaption></figcaption></figure>

#### Selected Display

The **Selected Display** setting chooses how events are presented. Each option provides a unique way of viewing your schedule:

<table><thead><tr><th width="134.419921875">Selected Display</th><th>Description</th><th>Image</th></tr></thead><tbody><tr><td><strong>Timeline</strong></td><td>Gives users a linear visual representation of their schedule over a selectable period.</td><td><img src="https://docs.avonnicomponents.com/~gitbook/image?url=https%3A%2F%2F27923732-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F1FUd4apB9YHgCEMUFbVb%252Fuploads%252Fmx9uHVTUIIQjBNGyr5KR%252F2023-06-21_14-05-33.png%3Falt%3Dmedia%26token%3D24649905-a630-44bf-bc0d-4d2457a09910&#x26;width=300&#x26;dpr=4&#x26;quality=100&#x26;sign=d98676dd&#x26;sv=2" alt="" data-size="original"></td></tr><tr><td><strong>Calendar</strong></td><td>This is the traditional grid-based view that most people associate with calendars.</td><td><img src="https://docs.avonnicomponents.com/~gitbook/image?url=https%3A%2F%2F27923732-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F1FUd4apB9YHgCEMUFbVb%252Fuploads%252FXZUwZSX7yIAzMIGPjVym%252F2023-06-21_14-06-37.png%3Falt%3Dmedia%26token%3Db194ae1b-1a2a-4d33-b1a3-25abbac7abeb&#x26;width=300&#x26;dpr=4&#x26;quality=100&#x26;sign=8a1f8bab&#x26;sv=2" alt="" data-size="original"></td></tr><tr><td><strong>Agenda</strong></td><td>Each entry in the list includes details about the event and is arranged chronologically.</td><td><img src="https://docs.avonnicomponents.com/~gitbook/image?url=https%3A%2F%2F27923732-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F1FUd4apB9YHgCEMUFbVb%252Fuploads%252FPTyhKXkJiX3XV0q9NOya%252F2023-06-21_14-07-11.png%3Falt%3Dmedia%26token%3D62d9f7bf-c963-476a-8462-ff543fb6acdb&#x26;width=300&#x26;dpr=4&#x26;quality=100&#x26;sign=a7101f65&#x26;sv=2" alt="" data-size="original"></td></tr></tbody></table>

* **Timeline**: A horizontal (or vertical) view of events over time — see all Room A's bookings for a week at a glance.
* **Calendar**: The classic grid layout with days in rows and columns — ideal for a monthly view of appointments.
* **Agenda**: A chronological list of events — "9 AM Meeting," "10 AM Call," listed in order by date.

#### Hidden Displays

The **Hidden Displays** setting removes one or more display modes from the toolbar. If only one or no display mode remains visible, the display-switch button is hidden entirely.

#### Timeline Variant

The **Timeline Variant** setting controls the orientation of the schedule when the **Timeline** display is selected. Choose **Horizontal** (default) for a left-to-right timeline, or **Vertical** to stack resources vertically. Requires: **Selected Display** = **Timeline**.

#### Selected Time Span

The **Selected Time Span** setting sets the active time span preset. The default presets are **Day**, **Week**, and **Month**. You can customize the available presets using the **Time Spans** advanced option.

#### Week Start Day

The **Week Start Day** setting controls which day appears first in the week — Sunday through Saturday. The **Default** option follows the user's locale.

#### Advanced Options

<figure><img src="/files/eqsNC3ZpOj6IM6jnOTAN" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="174.15625">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>Pull to Boundary</strong></td><td>When enabled, aligns the visible range to the nearest natural boundary for the chosen unit (for example, week or month boundaries), eliminating any margin between the calendar and the main component.</td></tr><tr><td><strong>Zoom to Fit</strong></td><td>When enabled in the timeline display, prevents horizontal scrolling by fitting all events within the viewable area for easy access and clear visualization.</td></tr><tr><td><strong>Today Button Label</strong></td><td>Customizes the label on the "Today" navigation button in the toolbar.</td></tr><tr><td><strong>Time Spans</strong></td><td>Defines the list of available time span presets. Each preset has a Label, Name, optional Icon, a Unit (Day, Week, or Month), a Span count, and Timeline Headers that control the horizontal header layout in the timeline display.</td></tr></tbody></table>

### Header

The **Header** section provides customization options for the toolbar displayed at the top of the Calendar.

<figure><img src="/files/alYFqpMP09l6ppbGd1Cd" alt=""><figcaption></figcaption></figure>

| Attribute                   | Description                                                                                                                                                                                          |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hide Header**             | If enabled, the entire toolbar is hidden.                                                                                                                                                            |
| **Caption**                 | Text displayed above the selected date in the toolbar. Requires: **Hide Header** = disabled.                                                                                                         |
| **Avatar**                  | Optional avatar displayed in the toolbar. Set an **Image**, a **Fallback Icon Name**, or **Initials**, and adjust the size and variant under Advanced Options. Requires: **Hide Header** = disabled. |
| **Actions**                 | Button actions added to the toolbar. Triggered based on the interactions created in the Interaction Panel. Requires: **Hide Header** = disabled.                                                     |
| **Visible Actions Buttons** | Maximum number of action buttons displayed directly in the toolbar before overflow behavior applies.                                                                                                 |
| **Hide Actions**            | If enabled, the actions menu is hidden.                                                                                                                                                              |
| **Disable Actions**         | If enabled, the actions menu is disabled.                                                                                                                                                            |

### Available Times

The **Available Times** section restricts which days, months, and time frames appear on your calendar, helping you focus on specific periods of interest.

<figure><img src="https://docs.avonnicomponents.com/~gitbook/image?url=https%3A%2F%2F27923732-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F1FUd4apB9YHgCEMUFbVb%252Fuploads%252F1a7555gp3de6rZyjSCT6%252F2024-02-18_21-01-35.png%3Falt%3Dmedia%26token%3D283e8292-8af2-40ed-8ef1-0c5fc53e766b&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=a4cecaf9&#x26;sv=2" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="138.3798828125">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>Days</strong></td><td>Restricts the calendar to only show selected days of the week. Unselected days are hidden.</td></tr><tr><td><strong>Months</strong></td><td>Restricts the calendar to only show selected months. Unselected months are hidden.</td></tr><tr><td><strong>Time Frames</strong></td><td><p>Defines custom time ranges shown in the calendar. Each time frame must follow the format <code>start-end</code> using ISO8601 time strings.</p><p><strong>Example:</strong> To show only 8 AM to 6 PM, enter <code>08:00-18:00</code>.</p></td></tr></tbody></table>

***

### Context Menu Actions

The **Context Menu Actions** section adds custom actions to context menus on your calendar, enhancing interactivity for both events and empty time slots.

<table><thead><tr><th width="187.544921875">Attribute</th><th>Description</th><th>Illustration</th></tr></thead><tbody><tr><td><strong>Event</strong></td><td>Actions displayed in the context menu and detail popover when interacting with an event. Use these to define custom actions users can perform directly on an event, such as editing or deleting it.</td><td><img src="/files/Y2s6U8WIlg0hS8q9RXpj" alt="" data-size="original"></td></tr><tr><td><strong>Empty Spot</strong></td><td>Actions displayed in the context menu when clicking on an empty spot in the calendar, such as creating a new event.</td><td><img src="/files/YBodjqam2oQ8nEKEqTA8" alt=""></td></tr></tbody></table>

***

### Event Display

The **Event Display** section customizes the visual appearance of calendar events.

<figure><img src="/files/4ahNM7xUWF3uqjSgaRR4" alt=""><figcaption></figcaption></figure>

**Theme**

The **Theme** setting chooses a visual style for all events. Options: **Default**, **Hollow**, **Line**, **Rounded**, or **Transparent**.

Theme variations

<figure><img src="https://docs.avonnicomponents.com/~gitbook/image?url=https%3A%2F%2F27923732-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F1FUd4apB9YHgCEMUFbVb%252Fuploads%252FwXhNLxhIPOisAMuAOBrL%252F2023-06-21_16-30-35.png%3Falt%3Dmedia%26token%3Dc93dd0a0-1bc6-403d-ab04-5fa2cfa8a652&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=d9bdf4ac&#x26;sv=2" alt=""><figcaption></figcaption></figure>

**Palette**

The **Palette** setting assigns different colors from a chosen palette to each resource. One color per resource ensures visual differentiation across the calendar. Options include: Aurora (default), Bluegrass, Dusk, Fire, Heat, Lake, Mineral, Nightfall, Ocean, Pond, Sunrise, Water, Watermelon, and Wildflowers.

**Popover Fields**

The **Popover Fields** setting defines which event fields are shown in the hover popover. By default, the **From** and **To** dates are shown. Add any event field by specifying its **Value** (the field key), an optional **Label**, and a display **Variant** (Standard, Label Hidden, Label Inline, or Label Stacked).

<figure><img src="/files/nBubKRsP2JKGana7NzOu" alt="" width="323"><figcaption></figcaption></figure>

Advanced options in the Event Display section include a **Custom Palette** to override the built-in palette with your own hexadecimal colors, a **Message When No Agenda Events Found** to customize the empty-state text shown in the Agenda display, and a **Number of Events Found Suffix** to customize the text appended after the event count in the Agenda header.

***

### Filter

The **Filter** section offers multiple customization options for the calendar's filter controls.

<figure><img src="/files/JjVbF7NWDzwzWijcSi3B" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="195.71875">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>Hide Resources Filter</strong></td><td>Hides the resources filter. In the timeline display this filter appears in the toolbar; in other displays it is found in the side panel.</td></tr><tr><td><strong>Resources Filter Label</strong></td><td>Renames the label of the resources filter. Requires: <strong>Hide Resources Filter</strong> = disabled.</td></tr><tr><td><strong>Hide Date Picker</strong></td><td>If enabled, the date picker in the calendar header is hidden and users cannot navigate to a specific date.</td></tr><tr><td><strong>Type</strong></td><td><p>Controls the layout of the filter menu. Options:</p><ul><li><strong>Horizontal:</strong> Displays filters in a horizontal bar across the component (default).</li><li><strong>Popover:</strong> Shows filters in a compact window that appears when a button is clicked.</li><li><strong>Panel:</strong> Presents filters in a side panel that slides out from the edge of the component.</li></ul></td></tr><tr><td><strong>Use Record Picklist Values</strong></td><td>When filtering by a picklist field, derives filter options from values present in the records rather than the field's full defined value set.</td></tr></tbody></table>

***

### Search

The **Search** section lets users find events by title using a search bar.

<figure><img src="/files/oojYpPACogUHuPZ5kuC2" alt=""><figcaption></figcaption></figure>

* **Show Search**: Enables the search bar.
* **Placeholder**: Sets the text displayed in the search bar before the user starts typing (for example, "Search Events"). Requires: **Show Search** = enabled.
* **Position**: Controls where the search bar appears — Left (default), Right, Center, Fill, or Panel. Requires: **Show Search** = enabled.

***

### Side Panel

The **Side Panel** section appears when filters or search are positioned in the panel layout.

<figure><img src="/files/Jtxz6603XQRmGdA4SFoL" alt=""><figcaption></figcaption></figure>

| Attribute              | Description                                                                                                                                  |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Position**           | Controls which side the panel slides out from — **Left** (default) or **Right**.                                                             |
| **Is Closed**          | If enabled, the side panel starts hidden when the page loads.                                                                                |
| **Hide Toggle Button** | If enabled, the toggle button in the header is hidden. Use this when you want the panel to open and close programmatically via interactions. |
| **Reset Button Label** | Customizes the label of the button used to reset all filter values.                                                                          |

### Set Component Visibility

All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).

## Interactions

[Interactions](/dynamic-components/component-builder/interactions.md) define what happens when users interact with the Calendar. Configure them from the **Interactions** tab of the Edit Calendar panel.

### Empty Spot Action Click

Fires when a user clicks one of the context menu actions on an empty time slot. Use the **targetName** output to identify which action was clicked, and use **clickedCellStart** and **clickedCellEnd** to capture the selected time range for creating new records.

### Event Action Click

Fires when a user clicks an action from an event's context menu or detail popover. Use the **targetName** output to identify which action was triggered, and **clickedEventActionEvent** (or **clickedEventActionEventSObject** for query data sources) to access the related event's data.

### Event Drag

Fires when a user finishes dragging an event to a new time slot or resource. Use **draggedEventName**, **draggedEventStart**, and **draggedEventEnd** to update the event's start date, end date, or resource assignment in Salesforce. Only active when at least one interaction is configured on this trigger.

### Event Select

Fires when a user clicks an event. Use **selectedEvent** (or **selectedEventSObject** for query data sources) to access the selected event's data and drive downstream logic such as navigation or record updates.

### New Event Drag

Fires when a user clicks or drags on an empty area of the schedule to create a new event. Use **newEventStart** and **newEventEnd** to capture the selected time range. Only active when at least one interaction is configured on this trigger.

### Toolbar Action Click

Fires when a user clicks one of the toolbar action buttons. Use the **targetName** output to identify which action was clicked and branch your flow logic accordingly.

### Toolbar Display Select

Fires when a user switches the active display mode from the toolbar (for example, from Calendar to Timeline). Use the **targetName** output to identify the selected display.

### Toolbar Time Span Select

Fires when a user selects a different time span preset from the toolbar (for example, switching from Day to Week). Use the **targetName** output to identify the selected time span.

## Output Variables

The Calendar exposes these output variables you can reference elsewhere on the page after the user interacts with it.

### Event Selection

When a user clicks an event, these variables update with the selected event's data.

| Output variable            | Type             | What it returns                                                                                                            |
| -------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Selected Event**         | Object           | The selected event's data — same properties as the static data source items (title, start date, end date, resource, etc.). |
| **Selected Event sObject** | Record (SObject) | The full Salesforce record associated with the selected event. Requires a **Query** data source.                           |

> **Example:** When a user clicks a calendar event for a case, use **Selected Event sObject** to display the case's details in a record-detail component beside the calendar.

### Event Context Menu Actions

When a user clicks an action from an event's context menu or detail popover, these variables update.

| Output variable                          | Type             | What it returns                                                                                 |
| ---------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------- |
| **Clicked Event Action - Name**          | Text (String)    | The name of the event action the user clicked.                                                  |
| **Clicked Event Action - Event**         | Object           | The event associated with the clicked action — same properties as the static data source items. |
| **Clicked Event Action - Event sObject** | Record (SObject) | The full Salesforce record associated with the event. Requires a **Query** data source.         |

> **Example:** When a user clicks an "Edit" action on an event, use **Clicked Event Action - Event sObject** to pre-populate a record edit form.

### Empty Spot Actions

When a user clicks an action from the context menu on an empty time slot, these variables update.

| Output variable              | Type          | What it returns                                                              |
| ---------------------------- | ------------- | ---------------------------------------------------------------------------- |
| **Clicked Cell Action Name** | Text (String) | The name of the empty spot action the user clicked.                          |
| **Clicked Cell Start**       | Text (String) | The start date and time of the empty time slot the user clicked or selected. |
| **Clicked Cell End**         | Text (String) | The end date and time of the empty time slot the user clicked or selected.   |

> **Example:** When a user clicks a "New Booking" action on an empty slot, use **Clicked Cell Start** and **Clicked Cell End** to pre-populate the start and end fields of a new event creation form.

### Event Drag

When a user finishes dragging an event to a new time slot or resource, these variables update.

| Output variable         | Type          | What it returns                                                        |
| ----------------------- | ------------- | ---------------------------------------------------------------------- |
| **Dragged Event Name**  | Text (String) | The unique name of the event that was dragged.                         |
| **Dragged Event Start** | Text (String) | The new start date and time of the dragged event after it was dropped. |
| **Dragged Event End**   | Text (String) | The new end date and time of the dragged event after it was dropped.   |

> **Example:** After a user drags a shift to a new time, use **Dragged Event Name**, **Dragged Event Start**, and **Dragged Event End** to update the corresponding record in Salesforce.

### New Event Drag

When a user clicks or drags on an empty area of the schedule to create a new event, these variables update.

| Output variable     | Type          | What it returns                                                                    |
| ------------------- | ------------- | ---------------------------------------------------------------------------------- |
| **New Event Start** | Text (String) | The start date and time of the new event the user created by clicking or dragging. |
| **New Event End**   | Text (String) | The end date and time of the new event the user created by clicking or dragging.   |

### Toolbar Actions

| Output variable                   | Type          | What it returns                                         |
| --------------------------------- | ------------- | ------------------------------------------------------- |
| **Clicked Toolbar Action - Name** | Text (String) | The name of the toolbar action button the user clicked. |

### Others

| Output variable     | Type   | What it returns                                              |
| ------------------- | ------ | ------------------------------------------------------------ |
| **Number of Items** | Number | The total number of events currently loaded in the calendar. |


---

# 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/dynamic-components/components/calendar.md?ask=<question>&goal=<endgoal>
```

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