Skip to content
Anniversary Countdown Sensor for Home Assistant
Branch: master
Clone or download
Latest commit 6c0f86f Jan 16, 2020
Type Name Latest commit message Commit time
Failed to load latest commit information.
custom_components/anniversaries Merge pull request #22 from kernehed/patch-1 Jan 16, 2020
LICENSE Update LICENSE Sep 11, 2019
hacs.json add unknown years info and weeks attribute Jan 14, 2020


hacs_badge GitHub release (latest by date) GitHub Release Date GitHub

Maintenance GitHub issues

Buy me a coffee

The 'anniversaries' component is a Home Assistant custom sensor which counts down to a recurring date such as birthdays, but can be used for any anniversary which occurs annually on the same date.

1.0.0 includes BREAKING CHANGES read the release notes.

Table of Contents



  1. Download the file from the latest release.
  2. Unpack the release and copy the custom_components/anniversaries directory into the custom_components directory of your Home Assistant installation.
  3. Configure the anniversaries sensor.
  4. Restart Home Assistant.


  1. Ensure that HACS is installed.
  2. Search for and install the "anniversaries" integration.
  3. Configure the anniversaries sensor.
  4. Restart Home Assistant.


Anniversaries can be configured on the integrations menu or in configuration.yaml

Config Flow

In Configuration/Integrations click on the + button, select Anniversaries and configure the options on the form.


Add anniversaries sensor in your configuration.yaml. The following example adds two sensors - Shakespeare's birthday and wedding anniversary!

# Example configuration.yaml entry

  - name: Shakespeare's Birthday
    date: '1564-04-23'
  - name: Shakespeare's Wedding Anniversary
    date: '1582-11-27'


Attribute Optional Description
name No Friendly name
date No date in format 'YYYY-MM-DD' (or 'MM-DD' if year is unknown)
icon_normal Yes Default icon Default: mdi:calendar-blank
icon_today Yes Icon if the anniversary 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 anniversary is 'soon' Default: mdi:calendar
date_format Yes formats the returned date Default: '%Y-%m-%d' for reference, see

State and Attributes


  • The number of days remaining to the next occurance.


  • years at next anniversary: number of years that will have passed at the next occurrence (NOT displayed if year is unknown)
  • current years: number of years have passed since the first occurance (ie, current age) (NOT displayed if year is unknown)
  • date: The date of the first occurence (or the date of the next occurence if year is unknown) (formatted by the date_format attribute if set)
  • weeks_remaining: The number of weeks until the anniversary
You can’t perform that action at this time.