WhenHub is a Home Assistant integration for tracking various events and important dates. The integration provides countdown sensors, status information, and visual representations for your events.
- Internationalization: Full German and English support - UI adapts to your HA language setting
- Localized Date Display: Date sensors now show relative time ("In 18 days", "Tomorrow") in the frontend
- Improved Sensor Classes: Proper
device_classfor duration and timestamp sensors - Lovelace Format Options: Use
format: relative,format: date, etc. in your cards
The origin story: The kids kept asking "How much longer until vacation?" or "How many days until my birthday?". I thought, there's got to be something I can do with Home Assistant! Now WhenHub displays an image of the event on the tablet with a big number showing the remaining days and the duration as text below.
Trip - Multi-day events like vacations or visiting grandma
Milestone - One-time important dates like school events or 'when is the new pet coming'
Anniversary - Yearly recurring events like birthdays or holidays
Special Event - Predefined holidays and astronomical events like Christmas, Easter, or Solstices
- Download the latest version from the Releases page
- Extract the files to the
custom_components/whenhubdirectory of your Home Assistant installation - Restart Home Assistant
- Go to Settings → Devices & Services → Add Integration
- Search for "WhenHub" and follow the configuration wizard
Trip events have a start date and end date and provide comprehensive tracking functions for multi-day events.
When setting up a Trip event, you configure:
- Event Name: e.g., "Denmark Vacation" or "Grandmas visit"
- Start Date: When the trip begins (Format: YYYY-MM-DD)
- End Date: When the trip ends (Format: YYYY-MM-DD)
- Image Path (optional):
- Leave empty = Automatically generated default image (blue airplane icon)
- File path = e.g.,
/local/images/denmark.jpgfor custom images - Base64 string = Directly embedded encoded image
- Website URL (optional): Link to accommodation or other relevant info
- Notes (optional): Additional information
- Event Date - Start date of the trip (ISO 8601 timestamp, displays as relative time)
- Attributes:
event_name- Name of the eventevent_type- Type of event (trip)end_date- End date (ISO format)trip_duration_days- Total trip duration in daysbreakdown_years- Years component of countdown until startbreakdown_months- Months component of countdown until startbreakdown_weeks- Weeks component of countdown until startbreakdown_days- Days component of countdown until start
- Attributes:
- Days Until Start - Days until trip begins (can become negative if date has passed)
- Days Until End - Days until trip ends (can become negative if date has passed)
- Trip Left Days - Remaining days during the trip
- Trip Left Percent - Remaining trip percentage (100% before start, decreases during trip, 0% after end)
- Trip Starts Today -
truewhen the trip starts today - Trip Active Today -
truewhen the trip is active today - Trip Ends Today -
truewhen the trip ends today
- Event Image - Shows the configured image or default image
- Attributes:
image_type- "user_defined" (custom image) or "system_defined" (default icon)image_path- Path to image, "base64_data" or "default_svg"
- Attributes:
Milestone events have a single target date and focus on the countdown to this important date.
When setting up a Milestone event, you configure:
- Event Name: e.g., "New car delivery" or "Project Deadline"
- Target Date: The important date (Format: YYYY-MM-DD)
- Image Path (optional):
- Leave empty = Automatically generated default image (red flag icon)
- File path = e.g.,
/local/images/birthday.jpgfor custom images - Base64 string = Directly embedded encoded image
- Website URL (optional): Relevant URL for the event
- Notes (optional): Additional information
- Event Date - Target date of the milestone (ISO 8601 timestamp, displays as relative time)
- Attributes:
event_name- Name of the eventevent_type- Type of event (milestone)breakdown_years- Years component of countdown until targetbreakdown_months- Months component of countdown until targetbreakdown_weeks- Weeks component of countdown until targetbreakdown_days- Days component of countdown until target
- Attributes:
- Days Until - Days until milestone (can become negative if date has passed)
- Is Today -
truewhen today is the milestone day
- Event Image - Shows the configured image or default image
- Attributes:
image_type- "user_defined" (custom image) or "system_defined" (default icon)image_path- Path to image, "base64_data" or "default_svg"
- Attributes:
Anniversary events repeat annually based on an original date and provide both retrospective and prospective functions.
When setting up an Anniversary event, you configure:
- Event Name: e.g., "Birthday Jon" or "Company Anniversary"
- Original Date: The date of the first event (Format: YYYY-MM-DD)
- Image Path (optional):
- Leave empty = Automatically generated default image (pink heart icon)
- File path = e.g.,
/local/images/wedding.jpgfor custom images - Base64 string = Directly embedded encoded image
- Website URL (optional): Relevant URL for the event
- Notes (optional): Additional information
- Event Date - Date of the next anniversary (ISO 8601 timestamp, displays as relative time)
- Attributes:
event_name- Name of the eventevent_type- Type of event (anniversary)initial_date- Original date (ISO format)years_on_next- Number of years at next anniversarybreakdown_years- Years component of countdown until next anniversarybreakdown_months- Months component of countdown until next anniversarybreakdown_weeks- Weeks component of countdown until next anniversarybreakdown_days- Days component of countdown until next anniversary
- Attributes:
- Days Until Next - Days until next anniversary
- Days Since Last - Days since last anniversary
- Occurrences Count - Number of past occurrences
- Next Date - Date of next anniversary (ISO 8601 timestamp)
- Last Date - Date of last anniversary (ISO 8601 timestamp)
- Is Today -
truewhen today is an anniversary day
- Event Image - Shows the configured image or default image
- Attributes:
image_type- "user_defined" (custom image) or "system_defined" (default icon)image_path- Path to image, "base64_data" or "default_svg"
- Attributes:
Anniversary events handle leap years intelligently: When the original date is February 29th, non-leap years automatically use February 28th.
Special events track holidays and astronomical events that repeat annually. These include both fixed-date holidays and calculated events with complex date algorithms.
When setting up a Special Event, you configure:
- Event Category: Choose from 3 categories (Traditional Holidays, Calendar Holidays, Astronomical Events)
- Event Name: e.g., "Weihnachts-Countdown" or "Oster-Countdown"
- Special Event Type: Choose from 17 predefined holidays and astronomical events
- Image Path (optional):
- Leave empty = Automatically generated default image (purple star icon)
- File path = e.g.,
/local/images/christmas.jpgfor custom images - Base64 string = Directly embedded encoded image
- Website URL (optional): Relevant URL for the event
- Notes (optional): Additional information
- Days Until - Days until next occurrence
- Days Since Last - Days since last occurrence
- Event Date - Date of the next occurrence (ISO 8601 timestamp, displays as relative time)
- Attributes:
event_name- Name of the eventevent_type- Type of event (special)special_type- Specific holiday type (e.g., "christmas", "easter")special_name- Display name of the holidaybreakdown_years- Years component of countdown until nextbreakdown_months- Months component of countdown until nextbreakdown_weeks- Weeks component of countdown until nextbreakdown_days- Days component of countdown until next
- Attributes:
- Next Date - Date of next occurrence (ISO 8601 timestamp)
- Last Date - Date of last occurrence (ISO 8601 timestamp)
- Is Today -
truewhen today is the special event day
- Event Image - Shows the configured image or default purple star icon
- Attributes:
image_type- "user_defined" (custom image) or "system_defined" (default icon)image_path- Path to image, "base64_data" or "default_svg"
- Attributes:
Special Events are organized into 3 categories with a total of 17 events:
Fixed and calculated events celebrating traditional holidays:
Fixed Date Events:
- Heilig Abend - December 24th (Christmas Eve)
- 1. Weihnachtstag - December 25th (Christmas Day)
- 2. Weihnachtstag - December 26th (Boxing Day)
- Halloween - October 31st
- Nikolaus - December 6th (St. Nicholas Day)
Calculated Events using the Gauss Easter Algorithm:
- Ostersonntag - Easter Sunday (base calculation)
- Pfingstsonntag - 49 days after Easter (Pentecost Sunday)
Advent Sundays (calculated from Christmas Eve):
- 1. Advent - 4th Sunday before Christmas Eve
- 2. Advent - 3rd Sunday before Christmas Eve
- 3. Advent - 2nd Sunday before Christmas Eve
- 4. Advent - Sunday before Christmas Eve
Fixed calendar events marking year transitions:
- Neujahr - January 1st (New Year's Day)
- Silvester - December 31st (New Year's Eve)
Fixed dates for seasonal transitions:
- Frühlingsanfang - March 20th (Spring Equinox)
- Sommeranfang - June 21st (Summer Solstice)
- Herbstanfang - September 23rd (Autumn Equinox)
- Winteranfang - December 21st (Winter Solstice)
Note: Astronomical events use simplified approximations. Actual dates may vary by ±1 day due to Earth's orbital mechanics.
Special Events uses the Gauss Easter Algorithm to calculate Easter dates without requiring lunar data or external dependencies. This algorithm:
- Works for any year in the Gregorian calendar
- Calculates Western (Catholic/Protestant) Easter
- Handles leap years and calendar irregularities automatically
- Provides the foundation for all Easter-dependent holidays
Advent Sundays are calculated by:
- Finding Christmas Eve (December 24th)
- Determining the day of the week
- Calculating backwards to find the 4th, 3rd, 2nd, and 1st Sundays before
- Special handling when Christmas Eve itself falls on a Sunday
Astronomical events use fixed dates for consistent scheduling:
- Spring Equinox: March 20th
- Summer Solstice: June 21st
- Autumn Equinox: September 23rd
- Winter Solstice: December 21st
These are simplified approximations for seasonal planning. For precise astronomical calculations, consider using specialized astronomy integrations.
WhenHub supports various types of images for your events:
- Custom Images: Use
/local/images/my-event.jpgfor your own images - Auto-generated Icons:
- Trip: Blue airplane icon
- Milestone: Red flag
- Anniversary: Pink heart
- Special Event: Purple star icon
- Supported Formats: JPEG, PNG, WebP, GIF, SVG
Images are stored in Home Assistant's www/ directory and referenced via /local/ paths.
The event_date sensor provides breakdown attributes for building localized countdown text:
breakdown_years- Years component (integer)breakdown_months- Months component (integer)breakdown_weeks- Weeks component (integer)breakdown_days- Days component (integer)
These values are calculated using approximations (365 days/year, 30 days/month) for consistent results. Use these attributes in Lovelace cards or templates to create formatted countdown text in your preferred language.
All event configurations can be edited after initial setup via the Options Flow:
- Go to Settings → Devices & Services → WhenHub
- Click Configure on the desired event
- Modify the settings for the respective event (Trip, Milestone, or Anniversary) and save
Note: Converting between event types (e.g., Trip to Anniversary) is not possible.
All sensors are automatically updated with the new data.
This project is open source and contributions are warmly welcomed! Issues for bugs or feature requests are just as appreciated as pull requests for code improvements.
⭐ Like WhenHub? Instead of buying me a coffee, give the project a star on GitHub!