# 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

![Add Custom Holiday](img/AddCustomHoliday.png)

## 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)

```json
{
  "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

```json
{
  "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

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

## Real-World Examples

### 1. Personal Birthdays
```json
{
  "name": "Mom's Birthday",
  "holiday_type": "fixed",
  "month": 5,
  "day": 12
}
```

### 2. School Events (Nth Weekday)
```json
{
  "name": "School Board Meeting",
  "holiday_type": "nth_weekday",
  "month": 1,
  "occurrence": 2,
  "weekday": 2
}
```
Second Wednesday of each month

### 3. Recurring End-of-Month
```json
{
  "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

```yaml
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

![Modify Custom Holiday](img/ModifyCustomHoliday.png)

### Delete a Custom Holiday

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

![Delete Custom Holiday](img/DeleteCustomHoliday.png)

**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](Holiday-Countdown.md) - Using holidays in countdown calculations
- [Auto-create Holiday Sensors](Holiday-Countdown.md#automatic-holiday-sensors) - Configure automatic sensor creation for built-in holidays