Skip to content
Calendarific holiday sensor for Home Assistant
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


GitHub release (latest by date) GitHub Release Date GitHub

Maintenance GitHub issues

Buy me a coffee

The 'Calendarific' component is a Home Assistant custom sensor which counts down to public holidays and observances, by querying the Calendarific api

State Returned:

  • The number of days remaining to the next occurance.

Attributes (both are provided by the Calendarific api:

  • date: The next date of the holiday (formatted by date_format configuration option if set)
  • description: The description of the holiday.

Table of Contents



  1. Download the file from the latest release.
  2. Unpack the release and copy the custom_components/calendarific directory into the custom_components directory of your Home Assistant installation.
  3. Configure the calendarific platform
  4. Restart Home Assistant.
  5. Configure sensors either in the configuration.yaml or by using the integrations page


  1. Ensure that HACS is installed.
  2. Search for and install the "calendarific" integration.
  3. Configure the calendarific platform.
  4. Restart Home Assistant.
  5. Configure sensors either in the configuration.yaml or by using the integrations page

Platform Configuration

You will need an API key from Go to the sign up page and open a new account. A free tier account is limited to 1000 api calls per month. This integration will make two calls per day (and two on home assistant start)

The Calendarific platform MUST be configured in the configuration.yaml file.

# Example configuration.yaml platform entry
  api_key: YOUR_API_KEY
  country: GB
  state: GB-WLS

Platform configuration parameters

Attribute Optional Description
api_key No your api key from
country No your country code here is a list of supported countries
state Yes your state code (ISO 3166-2 subdivision code) [USA] [UK] note the state code is for the country in the uk (counties not supported) or the state in the us. If omitted, only national holidays will be displayed

Sensor Configuration

Individual sensors can be configured using Config flow or in configuration.yaml:

Config Flow

In Configuration/Integrations click on the + button, select Calendarific and configure the options on the form (The available holidays will automatically appear on the list if the platform was configured correctly in the above step).


Add calendarific sensor in your configuration.yaml. The following example adds two sensors - New Year's Day and Christmas Day (Note that these must be entered EXACTLY as they are on the Calendarific server)

# Example configuration.yaml sensor entry
  - platform: calendarific
    holiday: New Year's Day
  - platform: calendarific
    holiday: Christmas Day

Sensor Configuration Parameters

Attribute Optional Description
holiday No Name of holiday provided by calendarific api
name Yes Friendly name Default: Holiday name
icon_normal Yes Default icon Default: mdi:calendar-blank
icon_today Yes Icon if the holiday is today Default: mdi:calendar-star
days_as_soon Yes Days in advance to display the icon defined in icon_soon Default: 1
icon_soon Yes Icon if the holiday is 'soon' Default: mdi:calendar
date_format Yes formats the returned date Default: '%Y-%m-%d' for reference, see
You can’t perform that action at this time.