Overview
The Calendar block is a full-featured date/time calendar supporting multiple view granularities. Its defining choice is the Event Type: how events are sourced and managed.
| Event Type | Description | When to Use |
| Object | The Calendar manages its own built-in event object store. Events have standard fields (title, start, end, color, notes). Users can create, edit, and delete events directly in the calendar. | You want a standalone meeting/task calendar without an external data source for events. |
| Mapped | You bind any data source array to the calendar, and map your own fields to the event shape (title, start, end, color, etc.). | You have existing data (appointments, tasks, bookings) in your backend and want to visualize it on a calendar. |
Tip: In Object mode, the block owns the event CRUD lifecycle — users create/edit/delete events directly in the UI. In Mapped mode, the block is read/display-only by default; mutations go through your own actions (e.g., API calls triggered by events).
Calendar Views
| View | Description |
| Month | Shows a full month grid. Events appear as compact colored bars on their dates. Best for a high-level overview. |
| Week | Shows a 7-day grid with hour rows. Events appear as time-block cards positioned by start and end time. Best for scheduling. |
| Day | Shows a single day with hour rows. Provides the most detail for a heavily scheduled day. |
Users can switch between views using the view-switcher in the calendar header. You can configure the Default View to control which view opens on load.
Content Properties — Object Mode
| Property | Description |
| Event Type | Set to Object. The calendar manages its own event list. |
| Default View | The calendar view shown on initial load: month, week, or day. |
| Show All Day Events | Toggle whether all-day events appear in the all-day row at the top of Week and Day views. |
| Allow Event Creation | Whether users can create new events by clicking or dragging on the calendar. |
| Allow Event Editing | Whether users can edit event details or drag events to new times. |
| Allow Event Deletion | Whether users can delete events from the calendar UI. |
Content Properties — Mapped Mode
| Property | Required | Description |
| Event Type | Required (required) | Set to Mapped. |
| Data Source | Required (required) | The array of records to render as events. |
| Title Field | Required (required) | The field to display as the event title on the calendar. |
| Start Date / Time Field | Required (required) | The ISO 8601 date-time field for the event start. For all-day events, a date-only field is accepted. |
| End Date / Time Field | Optional (optional) | The field for the event end. If omitted, events render as point-in-time (no duration block). |
| Color Field | Optional (optional) | A field whose value drives the event color. Can be a hex color string or a category value (mapped to a color via Chart Colours). |
| Resource Field | Optional (optional) | Used in Resource view (timeline) mode to group events by resource (e.g., room, agent). |
| Default View | The calendar view shown on initial load. |
Appearance Properties
| Property | Description |
| Show Weekend | Whether Saturday and Sunday columns are visible in Week view. |
| First Day of Week | The day the week starts on: Sunday or Monday. Affects month grid and week headers. |
| Slot Duration | The granularity of time slots in Week and Day views (e.g., 15 min, 30 min, 1 hour). |
| Business Hours | Highlights a defined range of hours as "business hours" in Day and Week views. Non-business hours are visually dimmed. |
| Event Colors | Default color palette for events. In Mapped mode, overridden by the Color field binding. |
| styles | Block dimensions, padding, overflow, height. |
Events
| Event | Available In | Description |
| On Event Click | Object & Mapped | Fires when the user clicks an event. Payload includes the event's full record (Mapped) or event object (Object). Use to open a detail drawer or form. |
| On Date Click | Object & Mapped | Fires when the user clicks an empty calendar cell. Payload includes the clicked date/time. Use to pre-fill a "New Event" form with the clicked date. |
| On Event Create | Object only | Fires when a new event is created by dragging on the calendar. Payload includes the new event object. |
| On Event Update | Object only | Fires when an event is edited (dragged to a new time or duration changed). Payload includes the updated event object. |
| On Event Delete | Object only | Fires when an event is deleted. Payload includes the deleted event's ID. |
| On View Change | Object & Mapped | Fires when the user switches views (month/week/day) or navigates to a different date range. Payload includes the new view and visible date range. Use to re-fetch data scoped to the visible range. |
Exposed State
| State Property | Type | Description |
| currentView | string | The currently active view: month, week, or day. |
| currentDate | date | The date currently focused or navigated to in the calendar header. |
| visibleDateRange.start | date | The first date currently visible in the calendar's viewport. |
| visibleDateRange.end | date | The last date currently visible in the calendar's viewport. |
| selectedEvent | object | The event the user most recently clicked, or null if none. |
Behavior & Gotchas
⚠ Mapped mode does not re-fetch on navigation automatically
The Calendar block does not automatically re-query your data source when the user navigates to a different month or week. You must listen to the On View Change event, read the new visibleDateRange from the block's state, and trigger your data source to re-fetch with those dates as filter parameters.
⚠ Date fields must be ISO 8601 strings or timestamps
The Calendar block parses start and end field values as dates. Inconsistent formats (e.g., mixing MM/DD/YYYY and ISO format) will cause events to appear on the wrong date or not appear at all. Standardize your date format in the data source.
⚠ Events without an end time render as point events
If you don't bind an End Date/Time field, events render as a single point in time (a narrow bar) rather than a duration block in Week/Day views. Bind an end time field for proper duration visualization.
⚠ Color field values must be valid hex or named colors
If you bind a Color field in Mapped mode, each record's color value must be a valid CSS color string (e.g., #3B82F6 or blue). If you want to color by category, use a computed field that maps category names to color strings.
Common Patterns
Appointments Calendar (Mapped + Drill-Down)
Set up the data source: Query appointments filtered by the visible date range. Expose start, end, patient name, and type fields.
Bind to Calendar (Mapped): Set Event Type = Mapped. Bind Title Field = patient name, Start = appointment start, End = appointment end, Color Field = type (use a computed color map).
Re-fetch on navigation: On On View Change, update a page variable with the new
visibleDateRange. Bind the data source query's date filter to this variable.Open appointment details: On On Event Click, store the payload in a page variable and open a detail drawer bound to that variable.
New Event Quick-Create
Handle On Date Click: On On Date Click, read the clicked date from the event payload and store it in a page variable.
Open a creation modal: Open a drawer or dialog containing a form for the new event. Pre-populate the start date field with the stored page variable.
Save and refresh: On form submit, call your API to create the event. After success, trigger the calendar's data source to refresh so the new event appears.
Frequently Asked Questions
What is the difference between Object mode and Mapped mode?
In Object mode, the Calendar block manages its own event data internally — users create, edit, and delete events directly in the calendar interface, and the block stores those events. In Mapped mode, you supply the events from your own data source and map your field names to the calendar's expected shape. Mapped mode is display-only by default; any mutations (creating/editing/deleting) require you to trigger API calls from event handlers.
How do I load only the events for the visible date range?
Listen to the On View Change event. When it fires, read the calendar block's visibleDateRange.start and visibleDateRange.end state properties and use them to set page variables. Bind your data source query's date filter parameters to those variables. When the variables update, the data source re-fetches automatically.
Can I open a form to create a new event when the user clicks an empty date?
Yes. Listen to the On Date Click event. The payload contains the clicked date. Store it in a page variable with a Set Variable action, then open a modal or drawer containing a creation form. Pre-populate the form's start-date field by binding it to the stored page variable.
Why are my events not showing on the correct date?
The most common causes are: (1) the Start Date/Time field is not in a parseable format — use ISO 8601 (YYYY-MM-DDTHH:mm:ssZ); (2) timezone handling is inconsistent between your data and the browser — ensure dates are UTC or include explicit timezone offsets; (3) you haven't re-fetched data after navigating to a new date range — wire up On View Change to trigger a re-fetch.
How do I color-code events by category?
In Mapped mode, bind the Color Field to a field in your data that contains a CSS color value (e.g., #FF5733). If your data has a category field (e.g., type: "Meeting"), add a computed column in your data transformer that maps each type to a color hex, then bind that computed column to the Color Field.