Calendar
The Calendar integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides calendar entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more], allowing other integrations to integrate calendars into Home Assistant. Calendars are shown on the calendar dashboard and can be used with automations.
This page does not provide instructions on how to create calendar entities. Please see the “Calendar” category on the integrations page to find integrations offering calendar entities. For example, Local Calendar is a fully local integration to create calendars and events within your Home Assistant instance or other integrations work with other services providing calendar data.
Building block integration
This calendar is a building block integration that cannot be added to your Home Assistant directly but is used and provided by other integrations.
A building block integration differs from the typical integration that connects to a device or service. Instead, other integrations that do integrate a device or service into Home Assistant use this calendar building block to provide entities, services, and other functionality that you can use in your automations or dashboards.
If one of your integrations features this building block, this page documents the functionality the calendar building block offers.
Viewing and managing calendars
Each calendar is represented as its own entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] in Home Assistant and can be viewed and managed on a calendar dashboard. You can find the calendar dashboard in the main sidebar of your Home Assistant instance.
Some calendar integrations allow Home Assistant to manage your calendars directly from Home Assistant. In this case, you can add new events by selecting the Add event button in the lower right corner of the calendar dashboard.
Also see Actions below.
The state of a calendar entity
The state shows whether or not there is an active event:
- On: The calendar has an active event.
- Off: The calendar does not have an active event.
In addition, the entity can have the following states:
- Unavailable: The entity is currently unavailable.
- Unknown: The state is not yet known.
Automation
Calendar Triggers enable automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more] based on an event’s start or end. Review the Automating Home Assistant getting started guide on automations or the Automation documentation for full details.
Calendar triggersA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [Learn more] are the best way to automate based on calendar events. A calendar entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] can also be used to automate based on its state, but these are limited and attributes only represent the next event.
An example of a calendar triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [Learn more] in YAML:
automation:
- triggers:
- trigger: calendar
# Possible values: start, end
event: start
# The calendar entity_id
entity_id: calendar.personal
# Optional time offset to fire a set time before or after event start/end
offset: -00:15:00
Calendar triggers should not generally use automation mode single
to ensure
the trigger can fire when multiple events start at the same time (e.g., use
queued
or parallel
instead). Note that calendars are read once every 15
minutes. When testing, make sure you do not plan events less than 15 minutes
away from the current time, or your triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [Learn more] might not fire.
See Automation Trigger Variables: Calendar for additional trigger data available for conditions or actions.
Automation recipes
Below are a few example ways you can use Calendar triggers.
Example: Calendar Event Notification
This example automation consists of:
- For the calendar entity
calendar.personal
. - At the start of any calendar event.
- Send a notification with the title and start time of the event.
- Allowing multiple events starting at the same time.
automation:
- alias: "Calendar notification"
triggers:
- trigger: calendar
event: start
entity_id: calendar.personal
actions:
- action: persistent_notification.create
data:
message: >-
Event {{ trigger.calendar_event.summary }} @
{{ trigger.calendar_event.start }}
Example: Calendar Event Light Schedule
This example consists of:
- For the calendar entity
calendar.device_automation
. - When event summary contains
Front Lights
. - Turn on and off light named
light.front
when the event starts and ends.
automation:
- alias: "Front Light Schedule"
triggers:
- trigger: calendar
event: start
entity_id: calendar.device_automation
- trigger: calendar
event: end
entity_id: calendar.device_automation
conditions:
- condition: template
value_template: "{{ 'Front Lights' in trigger.calendar_event.summary }}"
actions:
- if:
- "{{ trigger.event == 'start' }}"
then:
- action: light.turn_on
target:
entity_id: light.front
else:
- action: light.turn_off
target:
entity_id: light.front
Actions
Some calendar integrationsIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allow Home Assistant to manage your calendars directly using actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more]. The actions provided by some calendar entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] are described below or you can read more about actions.
Action calendar.create_event
Add a new calendar event. A calendar target
is selected with a Target Selector and the data
payload supports the following fields:
Data attribute | Optional | Description | Example |
---|---|---|---|
summary |
no | Acts as the title of the event. | Bowling |
description |
yes | The description of the event. | Birthday bowling |
start_date_time |
yes | The date and time the event should start. | 2019-03-10 20:00:00 |
end_date_time |
yes | The date and time the event should end (exclusive). | 2019-03-10 23:00:00 |
start_date |
yes | The date the whole day event should start. | 2019-03-10 |
end_date |
yes | The date the whole day event should end (exclusive). | 2019-03-11 |
in |
yes | Days or weeks that you want to create the event in. | “days”: 2 |
location |
yes | The location of the event. | Bowling center |
You either use start_date_time
and end_date_time
, or start_date
and end_date
, or in
.
This is a full example of a serviceThe term “service” in Home Assistant is used in the sense of an information service. For example, the municipal waste management service that provides entities for organic, paper, and packaging waste. In terms of functionality, the information service is like a device. It is called service to avoid confusion, as it does not come with a piece of hardware. [Learn more] call in YAML:
action: calendar.create_event
target:
entity_id: calendar.device_automation_schedules
data:
summary: "Example"
start_date: "2022-10-01"
end_date: "2022-10-02"
Home Assistant Calendars do not allow zero duration Calendar events. The following would create a one minute long event starting “now”. This could be used to record an external event in a Calendar.
action: calendar.create_event
target:
entity_id: calendar.device_automation_schedules
data:
summary: "Example"
start_date_time: "{{ now() }}"
end_date_time: "{{ now() + timedelta(minutes=1) }}"
Action calendar.get_events
This action populates Response Data with calendar events within a date range. It can return events from multiple calendars.
Data attribute | Optional | Description | Example |
---|---|---|---|
start_date_time |
yes | Return active events after this time (exclusive). When not set, defaults to now. | 2019-03-10 20:00:00 |
end_date_time |
yes | Return active events before this time (exclusive). Cannot be used with duration . You must specify either end_date_time or duration . |
2019-03-10 23:00:00 |
duration |
yes | Return active events from start_date_time until the specified duration. Cannot be used with end_date_time . You must specify either duration or end_date_time . |
days: 2 |
Use only one of end_date_time
or duration
.
action: calendar.get_events
target:
entity_id:
- calendar.school
- calendar.work
data:
duration:
hours: 24
response_variable: agenda
The response data contains a field for every calendar entity (e.g. calendar.school
and calendar.work
in this case).
Every calendar entity has a field events
containing a list of events with these fields:
Response data | Description | Example |
---|---|---|
summary |
The title of the event. | Bowling |
description |
The description of the event. | Birthday bowling |
start |
The date or date time the event starts. | 2019-03-10 20:00:00 |
end |
The date or date time the event ends (exclusive). | 2019-03-10 23:00:00 |
location |
The location of the event. | Bowling center |
This example uses a template with response data in another action:
action: notify.nina
data:
title: Daily agenda for {{ now().date() }}
message: >-
Your school calendar for today:
{% for event in agenda["calendar.school_calendar"]["events"] %}
{{ event.start}}: {{ event.summary }}<br>
{% endfor %}
Your work calendar for today:
{% for event in agenda["calendar.work_calendar"]["events"] %}
{{ event.start}}: {{ event.summary }}<br>
{% endfor %}