Custom Holidays

Custom Holidays

Define your own holidays for use in Holiday Countdown calculations. Custom holidays automatically create countdown sensors for every holiday you define.

Overview

Custom holidays allow you to create countdowns for birthdays, anniversaries, personal holidays, or any recurring date. Each custom holiday you create will automatically have a countdown sensor generated, making it easy to track important dates throughout the year.

Configuration

1. Go to Clockwork configuration
2. Select "Add Custom Holiday"
3. Fill in:
   • Holiday Display Name: A friendly name (e.g., "Alice's Birthday")
   • Holiday Type: How the date recurs
   • Additional fields based on type
   • Icon: Optional custom icon

Holiday Types

Type: "fixed"

Recurs on the same date every year.

Configuration:

• Month: 1-12
• Day: 1-31

Examples:

• Birthday (e.g., July 4)
• Anniversary (e.g., March 15)

{
  "name": "Wedding Anniversary",
  "holiday_type": "fixed",
  "month": 3,
  "day": 15
}

Type: "nth_weekday"

Recurs on a specific day of the week in a specific month (e.g., "2nd Monday of September").

Configuration:

• Month: 1-12
• Occurrence: 1-5 (first through fifth)
• Weekday: 0-6 (0=Monday, 6=Sunday)

Examples:

• Father's Day: 3rd Sunday of June
• Labor Day: 1st Monday of September

{
  "name": "Father's Day",
  "holiday_type": "nth_weekday",
  "month": 6,
  "occurrence": 3,
  "weekday": 6
}

Type: "last_weekday"

Recurs on the last occurrence of a day in a month.

Configuration:

• Month: 1-12
• Weekday: 0-6 (0=Monday, 6=Sunday)

Examples:

• Last Friday of the month
• Last Tuesday of July

{
  "name": "Month-End Report",
  "holiday_type": "last_weekday",
  "month": 1,
  "weekday": 4
}

Real-World Examples

1. Personal Birthdays

{
  "name": "Mom's Birthday",
  "holiday_type": "fixed",
  "month": 5,
  "day": 12
}

2. School Events (Nth Weekday)

{
  "name": "School Board Meeting",
  "holiday_type": "nth_weekday",
  "month": 1,
  "occurrence": 2,
  "weekday": 2
}

Second Wednesday of each month

3. Recurring End-of-Month

{
  "name": "Pay Day",
  "holiday_type": "last_weekday",
  "month": 1,
  "weekday": 4
}

Last Friday of the month

Using Custom Holidays

Once created, use in Holiday Countdown:

1. Add a "Holiday Countdown" calculation
2. Select your custom holiday from the Holiday list
3. Set offset if needed (e.g., -7 for countdown before)
4. Save and use in automations

Automation Example

automation:
  - alias: "Birthday reminder"
    trigger:
      platform: numeric_state
      entity_id: sensor.days_until_moms_birthday
      below: 8
      above: 0
    action:
      service: persistent_notification.create
      data:
        message: >
          Mom's birthday is in {{ 
          states('sensor.days_until_moms_birthday') }} days!
        title: Birthday Reminder

Management

Modify a Custom Holiday

1. Go to Clockwork configuration
2. Select "Modify Custom Holiday"
3. Choose the holiday to edit
4. Update the values
5. Save

Delete a Custom Holiday

1. Go to Clockwork configuration
2. Select "Delete Custom Holiday"
3. Choose the holiday to delete
4. Confirm deletion

Note: You can safely delete custom holidays; any Holiday Countdown calculations using them will need to be updated manually.

Automatic Sensors

Every custom holiday you create automatically generates a countdown sensor with the format sensor.days_until_{holiday_name} (with spaces converted to underscores and special characters removed).

Example: A custom holiday named "Mom's Birthday" will create a sensor sensor.days_until_moms_birthday that you can immediately use in automations.

Related Features

• Holiday Countdown - Using holidays in countdown calculations
• Auto-create Holiday Sensors - Configure automatic sensor creation for built-in holidays