Holiday

The Holiday integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] adds a calendarA calendar entity represents a schedule of events coming from a local or external calendar source. It can be used to trigger automations based on the start or end of an event, react to offsets (like 15 minutes before), or retrieve event details through services. [Learn more] with the public holidays for a country, and optionally a region within that country, to Home Assistant. You can use it to view upcoming holidays on your calendar dashboard and to power automations, for example, to keep the blinds closed on public holidays or turn on festive lights on a specific holiday.

The holiday data comes from the holidays library, which covers a large number of countries and their regions. No account or internet connection is needed.

Supported countries

The integration supports all countries and regions that the holidays library supports. When you add the integration, the Country list only shows supported countries. For the full list of countries, regions, and holiday categories, refer to the supported entities list of the holidays library.

Configuration

To add the Holiday integration to your Home Assistant instance, use this My button:

Manual configuration steps

If the above My button doesn’t work, you can also perform the following steps manually:

Country

The country to show holidays for. Defaults to the country set in your Home Assistant general settings.

Province

The province, state, or other region of the country. Some regions have extra or different holidays. Only shown if the selected country has regions.

Categories

Additional holiday categories to include, such as bank or school holidays. Public holidays are always included. Only shown if the selected country has additional categories. For the categories each country supports, refer to the holidays library.

You can add the integration more than once, for example, to show holidays for several countries or regions. Each combination of country, region, and categories can only be added once.

Options

To define options for Holiday, follow these steps:

  1. In Home Assistant, go to Settings > Devices & services.

  2. If multiple instances of Holiday are configured, choose the instance you want to configure.

  3. On the card, select the cogwheel .

    • If the card does not have a cogwheel, the integration does not support options for this device.

    Screenshot showing the cogwheel icon on an integration card in the Settings > Devices & services page

  4. Edit the options, then select Submit to save the changes.

Categories

Additional holiday categories to include. Public holidays are always included. If the country has no additional categories, the options are not available.

To change the province or region, or the categories, of an existing entry, use Reconfigure from the three dots menu on the entry.

Supported functionality

Each entry of the Holiday integration creates a service deviceA device is a model representing a physical or logical unit that contains entities. with one 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].

Calendar

  • Holiday calendar
    • Description: A read-only calendar with one all-day event for each holiday. The calendar is named after the country, and the region if you selected one, for example, calendar.germany. The event title is the name of the holiday, and the event location is the name of the calendar. If several holidays fall on the same date, they share one event, and the title lists all holiday names in alphabetical order, separated by a semicolon. For example, Christmas Day; Some other holiday.
    • State: On during a holiday, and Off on all other days.
    • Attributes: The attributes show the next upcoming holiday, such as its name (message), start and end time, and location.

A calendarA calendar entity represents a schedule of events coming from a local or external calendar source. It can be used to trigger automations based on the start or end of an event, react to offsets (like 15 minutes before), or retrieve event details through services. [Learn more] entity has a state and attributes that represent the next upcoming event (only). A calendar trigger is a much more flexible way to power automations with fewer limitations than using the entity state.

Holiday automation examples

Each holiday date is a calendar event, so you can use a calendar trigger to start an automation when a holiday begins or ends. Holidays on the same date share one event with a combined title, so check whether the title contains the holiday name instead of matching the full title. You can also use the calendar state in a condition to check whether today is a holiday. For an overview, refer to calendar automations. You can use calendar trigger variables, such as the event summary and location, in conditions and actions.

Tip

You don’t need to edit YAML to use these examples. Copy a YAML snippet from this page, open the visual automation editor in Home Assistant, and press Ctrl+V (or Cmd+V on Mac). Home Assistant automatically converts the pasted YAML into the visual editor format, whether it’s a full automation, a single trigger, a condition, or an action.

Automation: Turn on the Christmas lights on Christmas Day

Turn on your festive lights when Christmas Day starts. The condition checks the name of the holiday, so the automation only runs on Christmas Day and not on other holidays. It also works when another holiday falls on the same date. The holiday name must match the name shown on your calendar, which depends on your language.

  • Trigger: Calendar event starts
    • Target: Germany (calendar.germany)
  • Condition: The event title includes Christmas Day
  • Action: Turn on light
    • Target: Christmas lights (light.christmas_lights)
YAML example for turning on the Christmas lights
AutomationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more]
alias: "Turn on the Christmas lights on Christmas Day"
triggers:
  - trigger: calendar
    event: start
    entity_id: calendar.germany
conditions:
  - "{{ 'Christmas Day' in trigger.calendar_event.summary.split('; ') }}"
actions:
  - action: light.turn_on
    target:
      entity_id: light.christmas_lights

Automation: Keep the covers closed on public holidays

Open your covers in the morning on regular days, but let you sleep in on public holidays. The condition checks that the holiday calendar is Off, which means today is not a holiday.

  • Trigger: Time is 07:00
  • Condition: Germany (calendar.germany) is Off
  • Action: Open cover
    • Target: Bedroom blinds (cover.bedroom_blinds)
YAML example for keeping the covers closed on public holidays
AutomationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more]
alias: "Open the bedroom blinds on non-holidays"
triggers:
  - trigger: time
    at: "07:00:00"
conditions:
  - condition: state
    entity_id: calendar.germany
    state: "off"
actions:
  - action: cover.open_cover
    target:
      entity_id: cover.bedroom_blinds

Data updates

The holiday data is included in the integration, so no data is fetched from the internet. The calendar updates its state at the start of each day. New holidays and corrections come from updates of the holidays library, which are included in Home Assistant updates.

Known limitations

  • The calendar is read-only. You cannot add, change, or remove holidays.
  • All holidays are all-day events. Holidays from the Half day category also show as all-day events.
  • Holidays on the same date share one event. The event title combines the holiday names, separated by a semicolon.
  • The country of an existing entry cannot be changed. To show holidays for another country, add the integration again.
  • Holiday names use the system language of Home Assistant, set under Settings > System > General, if the country supports it. Otherwise, they use the main language of the country. The language you select in your user profile is not used. The language is set when the integration starts, so after you change the system language, reload the integration.
  • The name of the calendar is set in the system language when you add the integration. It does not change when you change the language later.
  • The calendar only shows holidays, not regular workdays or weekends. To check whether a day is a workday, use the Workday integration.

Troubleshooting

My country is not in the list

Symptom: The country is not available when adding the integration

When you add the integration, your country does not show up in the Country list.

Description

The Country list only shows countries supported by the holidays library.

Resolution

Check the list of supported countries. If your country is not supported, you can request it in the holidays library repository. Once support is added, it becomes available in a later Home Assistant release.

\Already configured\ when adding the integration

Symptom: “Already configured”

When you add the integration or change its settings, the form shows the message “Already configured. Only a single configuration for country/province/categories combination is possible.”

Description

An entry with the same country, region, and categories already exists.

Resolution

Use the existing entry, or select a different region or different categories.

\The country has no additional categories to configure\

Symptom: The options cannot be opened

When you select Configure on the entry, the message “The country has no additional categories to configure” is shown.

Description

The selected country only has public holidays, so there are no extra categories to choose from.

Resolution

No action is needed. Public holidays are always included.

Holiday names are in the wrong language

Symptom: Holiday names are shown in another language

The names of the holidays on the calendar are not in the language you use in Home Assistant.

Description

The integration uses the system language of Home Assistant, not the language you select in your user profile. The holidays library also does not have translations for every country. If your language is not available for the country, the names use the main language of that country. The language is only set when the integration starts.

Resolution

  1. Go to Settings > System > General and check that Language is set to the language you want.
  2. If you changed the language, go to Settings > Devices & services, select Holiday, and reload the entry.
  3. If the names are still in another language, your language is not available for this country in the holidays library.
A holiday is missing or on the wrong date

Symptom: A holiday is missing or has the wrong date

A holiday you expect is not on the calendar, or it shows on the wrong day.

Description

Some holidays only apply to a region or to an additional category, such as bank or school holidays. The holiday data itself comes from the holidays library.

Resolution

  1. Check that you selected the correct region. To change it, use Reconfigure from the three dots menu on the entry.
  2. Check whether the holiday belongs to an additional category. To add categories, select Configure on the entry.
  3. If the holiday is still missing or wrong, report it in the holidays library repository.

Removing the integration

This integration follows standard integration removal. No extra steps are required.

To remove an integration instance from Home Assistant

  1. Go to Settings > Devices & services and select the integration card.
  2. Next to the entry you want to remove, select the three dots menu. Then, select Delete.
    • Depending on the integration, the entries are listed under one of the following headings:
      • Devices
      • Hubs
      • Services
      • Integration entries
  3. To confirm, select Delete.
    • Home Assistant also deletes the devices and entities of the entry.
  4. If Home Assistant asks you to restart, restart Home Assistant.
  5. If Home Assistant asks whether to also delete the application credentials, select Remove or Keep.