### Install Dependencies and Start Development

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/CONTRIBUTING.md

Install project dependencies and start the development server.

```bash
npm install
npm run dev
```

--------------------------------

### Start Development Server

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Execute this command to start the development server and begin working on the project.

```sh
npm run dev
```

--------------------------------

### Tap Action Examples

Source: https://context7.com/alexpfau/calendar-card-pro/llms.txt

Examples of different tap actions for the calendar card.

```yaml
tap_action:
  action: url
  url_path: https://calendar.google.com
```

```yaml
tap_action:
  action: call-service
  service: notify.mobile_app_phone
  service_data:
    message: "Check your calendar!"
```

```yaml
tap_action:
  action: none               # Disable interaction
```

--------------------------------

### Full Example Configuration

Source: https://context7.com/alexpfau/calendar-card-pro/llms.txt

A comprehensive configuration example for the Calendar Card Pro, demonstrating various options.

```yaml
type: custom:calendar-card-pro

entities:
  - entity: calendar.family
    color: '#ffdaea'
    accent_color: '#ff6c92'
    label: '🏠'
  - entity: calendar.work
    color: '#b3ffd9'
    accent_color: '#43a047'
    label: 'mdi:briefcase'
    compact_events_to_show: 3
    blocklist: 'OOO'

start_date: 'today'
days_to_show: 10
compact_events_to_show: 5
compact_events_complete_days: true
filter_duplicates: true
language: en

title: '📅 My Calendar'
title_font_size: '20px'
title_color: 'var(--primary-color)'

background_color: 'var(--ha-card-background)'
accent_color: '#03a9f4'
vertical_line_width: '3px'
event_background_opacity: 10
day_spacing: '8px'
event_spacing: '5px'
max_height: '500px'

today_indicator: pulse
today_indicator_color: '#03a9f4'
today_day_color: '#03a9f4'
weekend_day_color: '#e67c73'

show_week_numbers: iso
week_separator_width: 1px
month_separator_width: 2px

show_time: true
time_24h: system
show_end_time: true
show_location: true
remove_location_country: true
show_description: true
description_max_lines: 2
show_countdown: true
show_progress_bar: true
show_past_events: false

weather:
  entity: weather.forecast_home
  position: date
  date:
    show_conditions: true
    show_high_temp: true
    show_low_temp: true

tap_action:
  action: expand
hold_action:
  action: navigate
  navigation_path: /lovelace/calendar

refresh_interval: 30
refresh_on_navigate: true
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Run this command in your local clone to install all necessary project dependencies.

```sh
npm install
```

--------------------------------

### Manual Installation Resource

Source: https://context7.com/alexpfau/calendar-card-pro/llms.txt

Configuration for manual installation of Calendar Card Pro as a Lovelace resource.

```yaml
# /config/configuration.yaml → Lovelace resources
url: /local/calendar-card-pro.js
type: module
```

--------------------------------

### Clone Repository

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/CONTRIBUTING.md

Clone your forked repository to start development.

```bash
git clone https://github.com/[your-username]/calendar-card-pro.git
```

--------------------------------

### Core Display Settings: Days, Start Date, and Compact Controls

Source: https://context7.com/alexpfau/calendar-card-pro/llms.txt

Configures the number of days to display, a fixed or relative start date, and compact mode settings for event visibility. The 'tap_action' can be set to 'expand' to reveal full details.

```yaml
type: custom:calendar-card-pro
entities:
  - calendar.family

# How many days to fetch from the API and show when expanded
days_to_show: 7

# Fixed or relative start date
start_date: 'today+1'   # tomorrow; also accepts '2025-07-01', '-2', 'today-3'

# Compact mode: show only the first 5 events; tap to expand to full 7 days
compact_events_to_show: 5
compact_days_to_show: 2          # Cap to 2 days in compact mode
compact_events_complete_days: true  # Never cut off a day mid-list

tap_action:
  action: expand
```

--------------------------------

### Set Dynamic Start Date with Relative Offsets

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Configure a dynamic start date using offsets relative to the current date. Use shorthand like '+3' or '-1' for convenience.

```yaml
start_date: "today+7"  # Always show events starting 7 days in the future
start_date: "+3"       # Shorthand for today+3 (3 days from today)
start_date: "today-2"  # Show events starting from 2 days ago
start_date: "-1"       # Shorthand for today-1 (yesterday)
```

--------------------------------

### Add Calendar Card Pro Resource (Manual Install)

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Use this YAML configuration to add the Calendar Card Pro as a resource in your Home Assistant Lovelace Dashboard when installing manually. Ensure the file path matches your configuration.

```yaml
url: /local/calendar-card-pro.js
type: module
```

--------------------------------

### Dynamic Start Date with Relative Offsets

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/RELEASE_NOTES.md

Define flexible start dates for event display using relative offsets. Options like `today+7`, `+3`, `today-2`, and `-1` allow the date range to automatically update relative to the current day.

```yaml
# Start date examples:
start_date: "today+7"  # Always show events starting 7 days from today
start_date: "+3"       # Shorthand for today+3
start_date: "today-2"  # Show events starting from 2 days ago
start_date: "-1"       # Shorthand for today-1 (yesterday)
```

--------------------------------

### Example: Per-Calendar and Global Event Limits

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Demonstrates how to set global and per-calendar limits for events shown in compact view. In expanded view, only per-calendar limits are enforced. Entity-specific limits are always respected.

```yaml
entities:
  - entity: calendar.family
    # No limit for family calendar
  - entity: calendar.work
    compact_events_to_show: 2
    # Never show more than 2 work events
  - entity: calendar.holidays
    compact_events_to_show: 1
    # Only show 1 holiday event
compact_events_to_show: 4
# Show at most 4 events total in compact mode

tap_action:
  action: expand
```

--------------------------------

### Example Translation File Structure

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/CONTRIBUTING.md

Structure for a language JSON file used for translations in Calendar Card Pro.

```json
{
  "daysOfWeek": ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
  "fullDaysOfWeek": ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
  "months": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
  "allDay": "all-day",
  "multiDay": "until",
  "at": "at",
  "endsToday": "ends today",
  "endsTomorrow": "ends tomorrow",
  "noEvents": "No upcoming events",
  "loading": "Loading calendar events...",
  "error": "Error: Calendar entity not found or improperly configured"
}
```

--------------------------------

### Pure Function Rendering Example (TypeScript)

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/architecture.md

Demonstrates the pure function approach for rendering events, generating TemplateResults. Ensure all necessary types and utilities are imported.

```typescript
export function renderEvent(
  event: Types.CalendarEventData,
  day: Types.EventsByDay,
  index: number,
  config: Types.Config,
  language: string,
): TemplateResult {
  // Determine styles and classes based on event properties
  const eventClasses = {
    event: true,
    'event-first': index === 0,
    'event-last': index === day.events.length - 1,
    'past-event': isPastEvent(event),
  };

  // Return immutable template
  return html`
    <tr>
      ${index === 0 ? html`<td class="date-column" rowspan="${day.events.length}">...</td>` : ''}
      <td class=${classMap(eventClasses)} style=${styleMap(eventStyles)}>
        <!-- Event content -->
      </td>
    </tr>
  `;
}
```

--------------------------------

### Set Fixed Start Date

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Configure a fixed start date for the calendar view using YYYY-MM-DD format.

```yaml
start_date: '2025-07-01' # Always start from July 1st, 2025
```

--------------------------------

### Configure Dynamic Date Range

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Display a floating window of days starting from a relative date offset. The window automatically adjusts as time passes.

```yaml
start_date: '+7' # One week from today
days_to_show: 7 # Shows a 7-day window starting one week from today
```

--------------------------------

### Configure Fixed Date Range

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Display a fixed number of days starting from a specific date. This creates a static calendar view.

```yaml
start_date: '2025-07-01'
days_to_show: 14 # Shows July 1-14, 2025
```

--------------------------------

### Example Regex for Location Country Removal

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

An example configuration using a regex pattern to remove specific country names like 'USA' or 'United States' from addresses, while preserving others.

```yaml
remove_location_country: 'USA|United States|U.S.A.|U.S.'

```

--------------------------------

### Configure Event Time Display

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Control the visibility and formatting of event start and end times. Options include 24-hour format, showing two-digit hours, and customizing font size and color.

```yaml
# Time display options
show_time: true # Show event start/end times
show_single_allday_time: false # Hide time for single-day all-day events
time_24h: false # Use 12-hour format (AM/PM)
time_two_digit_hours: false # Use 2 digits in hours
show_end_time: true # Show event end time
time_font_size: '12px'
time_color: 'var(--secondary-text-color)'
time_icon_size: '14px'
```

--------------------------------

### Full Calendar Card Pro Configuration

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Demonstrates all available options for styling, layout, and interactions. Includes core settings, header customization, layout adjustments, and date column styling.

```yaml
type: custom:calendar-card-pro

# Core Settings
entities:
  - entity: calendar.family
    color: '#ffdaea'
  - entity: calendar.work
    color: '#b3ffd9'
start_date: '2025-07-01'
days_to_show: 10
compact_events_to_show: 10
language: en

# Header
title: 📅 Full Calendar Demo
title_font_size: 26px
title_color: '#baf1ff'

# Layout and Spacing
background_color: '#eeeeee50'
accent_color: '#baf1ff'
vertical_line_width: 0px
row_spacing: 10px
additional_card_spacing: 0px

# Week Numbers and Horizontal Separators
day_separator_width: 2px
day_separator_color: '#baf1ff80'

# Date Column
date_vertical_alignment: middle
weekday_font_size: 14px
weekday_color: '#baf1ff'
day_font_size: 32px
day_color: '#baf1ff'
show_month: true
month_font_size: 12px
month_color: '#baf1ff'
```

--------------------------------

### Configure Actions and Interactions

Source: https://context7.com/alexpfau/calendar-card-pro/llms.txt

Define tap and hold actions for events. Supports standard Home Assistant actions like 'more-info' and 'navigate', as well as a card-specific 'expand' action for toggling compact/expanded views.

```yaml
type: custom:calendar-card-pro
entities:
  - calendar.family
compact_events_to_show: 5

# Tap toggles compact ↔ expanded view
tap_action:
  action: expand

# Long-press navigates to the full calendar view
hold_action:
  action: navigate
  navigation_path: /lovelace/calendar

# Other supported actions:
# tap_action:
#   action: more-info          # Opens HA entity dialog
```

--------------------------------

### Open a URL on Long Press

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Sets up a hold action to open an external URL. The URL to be opened is specified with `url_path`.

```yaml
hold_action:
  action: url
  url_path: https://calendar.google.com
```

--------------------------------

### Enable Countdown Display for Events

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Activate the countdown display feature to show remaining time until an event starts. The countdown appears in a natural language format next to upcoming events.

```yaml
# Enable countdown display for events
show_countdown: true
```

--------------------------------

### Enable Expand/Collapse with Tap Action

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Configures the card to expand and collapse the event list when tapped. This action allows users to toggle between the compact and full view of events.

```yaml
tap_action:
  action: expand
```

--------------------------------

### Blocklist Event Filtering Example

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/RELEASE_NOTES.md

Exclude specific events from being displayed by using a regex-based `blocklist` pattern for a calendar entity. This is useful for hiding recurring events like private meetings or conferences.

```yaml
entities:
  - entity: calendar.work
    blocklist: "Private|Conference" # Hide private meetings and conferences
```

--------------------------------

### Configure Global Compact View Limits

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Set global limits for the number of days and events displayed in the compact view using `days_to_show`, `compact_events_to_show`, and `compact_days_to_show`. Ensure complete days are shown with `compact_events_complete_days`.

```yaml
days_to_show: 7
compact_events_to_show: 5
compact_days_to_show: 2
compact_events_complete_days: true
```

--------------------------------

### Split Parameters for Icon Sizes

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/RELEASE_NOTES.md

The `time_location_icon_size` parameter has been split into `time_icon_size` and `location_icon_size` for more granular control.

```yaml
time_icon_size: '14px'
location_icon_size: '14px'
```

--------------------------------

### Integrate Weather Forecasts in Calendar Card Pro

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Display weather forecasts alongside calendar events. Configure the weather entity and specify where to show weather information (date, event, or both).

```yaml
type: custom:calendar-card-pro
entities:
  - calendar.family
days_to_show: 5
weather:
  entity: weather.forecast_home
  position: both
  date:
    show_conditions: true
    show_high_temp: true
    show_low_temp: false
    icon_size: '16px'
    font_size: '14px'
    color: '#3498db'
  event:
    show_conditions: false
    show_temp: true
    font_size: '13px'
    color: 'var(--secondary-text-color)'
```

--------------------------------

### Configure Week Numbers and Visual Separators

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Enable and style week numbers and visual separators for improved calendar organization. Supports ISO or simple week numbering.

```yaml
# Week number configuration
show_week_numbers: 'iso' # 'iso', 'simple', or null to disable
show_current_week_number: true # Show week number for the first week
first_day_of_week: 'monday' # 'monday', 'sunday', or 'system'

# Week number styling
week_number_font_size: '12px'
week_number_color: 'var(--primary-text-color)'
week_number_background_color: '#03a9f450'

# Separator configuration
day_separator_width: '1px' # Line between days
day_separator_color: '#03a9f430'
week_separator_width: '2px' # Line between weeks
week_separator_color: '#03a9f480'
month_separator_width: '3px' # Line between months
month_separator_color: '#03a9f4'
```

--------------------------------

### Configure Layout, Spacing, and Dimensions

Source: https://context7.com/alexpfau/calendar-card-pro/llms.txt

Adjust the overall height, maximum height, and spacing between days and events. Customize background and accent colors, including the vertical line width and event row tinting.

```yaml
type: custom:calendar-card-pro
entities:
  - calendar.family

# Sizing
height: 'auto'          # Fixed exact height, e.g. '300px'
max_height: '400px'     # Grows with content up to limit; scrolls beyond
additional_card_spacing: '10px'

# Spacing
day_spacing: '8px'
event_spacing: '6px'

# Colors / accent line
background_color: '#eeeeee50'
accent_color: '#03a9f4'         # Global fallback vertical line color
vertical_line_width: '3px'
event_background_opacity: 15    # 0-100: tints event rows with accent_color
```

--------------------------------

### Configure Weather Integration in YAML

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/RELEASE_NOTES.md

Use this YAML configuration to set up weather forecasts within Calendar Card Pro. Specify the weather entity and choose display options for date and event columns.

```yaml
type: custom:calendar-card-pro
# Basic weather configuration
weather:
  entity: weather.your_weather_entity
  position: date # Options: 'date', 'event', or 'both'
  date:
    show_conditions: true
    show_high_temp: true
    show_low_temp: false
  event:
    show_conditions: true
    show_temp: true
```

--------------------------------

### Add Versioned Resource to Home Assistant

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/CONTRIBUTING.md

Add a version query parameter to the resource URL to bypass Home Assistant's caching mechanism.

```yaml
url: /hacsfiles/calendar-card-pro/calendar-card-pro-dev.js?v=1
type: module
```

--------------------------------

### Directory Structure for Calendar Card Pro

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/architecture.md

This outlines the organization of the Calendar Card Pro project, detailing the purpose of each directory and key files.

```tree
src/
├── calendar-card-pro.ts          # Main entry point and component class
├── config/
│   ├── config.ts                 # DEFAULT_CONFIG and config helpers
│   ├── constants.ts              # Application constants and defaults
│   └── types.ts                  # TypeScript interface definitions
├── interaction/
│   ├── actions.ts                # Action execution (tap, hold, etc.)
│   └── feedback.ts               # Visual feedback (ripple, hold indicators)
├── rendering/
│   ├── editor.ts                 # Card editor component
│   ├── editor.styles.ts          # Editor-specific CSS styles
│   ├── render.ts                 # Component rendering functions
│   └── styles.ts                 # CSS styles and dynamic styling
├── translations/
│   ├── dayjs.ts                  # Day.js locale configuration
│   ├── localize.ts               # Translation functions
│   └── languages/                # Translation files (33 supported languages)
│       ├── en.json               # English translations
│       ├── de.json               # German translations
│       └── ...                   # Other language files
└── utils/
    ├── events.ts                 # Calendar event fetching and processing
    ├── format.ts                 # Date and text formatting
    ├── helpers.ts                # Generic utilities (color, ID generation)
    ├── logger.ts                 # Logging system
    └── weather.ts                # Weather data fetching and processing
```

--------------------------------

### Highlight Tomorrow's Events in Calendar Card Pro

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Style tomorrow's events similarly to today's, using the 'tomorrow' class for distinct visual emphasis. Requires card-mod.

```yaml
type: custom:calendar-card-pro
card_mod:
  style: |
    /* Make tomorrow's events stand out */
    .day-table.tomorrow .event-title {
      font-size: 16px !important;     /* Larger text */
      font-weight: bold !important;   /* Bold text */
      color: var(--accent-color) !important; /* Use theme accent color */
    }
```

--------------------------------

### Add Calendar Card Resource to Home Assistant

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/CONTRIBUTING.md

Configure Home Assistant to use the development version of the calendar card.

```yaml
url: /hacsfiles/calendar-card-pro/calendar-card-pro-dev.js
type: module
```

--------------------------------

### Multiple Calendars with Compact Mode

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Integrates multiple calendars with custom colors and uses compact mode to limit visible events. Tap to expand.

```yaml
type: custom:calendar-card-pro
title: Upcoming events
entities:
  - entity: calendar.family
    color: '#ff6c92' # Red for family events
  - entity: calendar.work
    color: '#86ebda' # Blue for work events
  - entity: calendar.personal
    color: '#c2ffb3' # Green for personal events
days_to_show: 7
compact_events_to_show: 3 # Always only show 3 events
tap_action:
  action: expand # Tap to expand/collapse
```

--------------------------------

### Multi-Calendar Configuration with Per-Calendar Styling

Source: https://context7.com/alexpfau/calendar-card-pro/llms.txt

Configures multiple calendars with individual styling options like color, accent color, labels, and event limits. Supports blocklist and allowlist for filtering events.

```yaml
type: custom:calendar-card-pro
entities:
  # Simple form – inherits all global defaults
  - calendar.holidays

  # Object form – full per-calendar control
  - entity: calendar.work
    color: '#86ebda'               # Event title color
    accent_color: '#1e88e5'        # Vertical line + background tint
    label: 'mdi:briefcase'         # MDI icon label (or emoji / text)
    label_icon_color: '#1e88e5'    # Icon-label color
    show_time: true
    show_location: false
    show_description: true
    compact_events_to_show: 2      # Max events from this calendar in compact mode
    blocklist: 'OOO|Holiday'       # RegExp – hide matching events
    # allowlist: 'Standup|Sprint'  # RegExp – show only matching events (takes precedence)
    split_multiday_events: true

  - entity: calendar.personal
    color: '#ff6c92'
    accent_color: '#e91e63'
    label: '🏠'
```

--------------------------------

### Frameless Calendar Card Pro Integration

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Remove borders, shadows, and background from the card to integrate it seamlessly as a frameless element. Requires card-mod.

```yaml
type: custom:calendar-card-pro
card_mod:
  style: |
    ha-card {
      border-radius: 0;
      border: none;
      box-shadow: none;
      background: transparent !important;
    }
```

--------------------------------

### Show Past Events Configuration

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/RELEASE_NOTES.md

Enable and configure the display of past events. When `show_past_events` is enabled, past events will be dimmed with 60% opacity for better visual hierarchy.

```yaml
show_past_events: true
```

--------------------------------

### Highlight Today's Events in Calendar Card Pro

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Style today's events to stand out with larger, bold text and a distinct color. Includes a subtle pulsing animation on the left border. Requires card-mod.

```yaml
type: custom:calendar-card-pro
card_mod:
  style: |
    /* Make today's events stand out */
    .day-table.today .event-title {
      font-size: 16px !important;     /* Larger text */
      font-weight: bold !important;   /* Bold text */
      color: var(--accent-color) !important; /* Use theme accent color */
    }

    /* Add subtle left border pulse animation */
    .day-table.today .event {
      border-left-width: 4px !important;
      transition: border-left-color 1s ease-in-out;
      animation: todayPulse 3s infinite alternate;
    }

    @keyframes todayPulse {
      from { border-left-color: var(--accent-color); }
      to { border-left-color: var(--primary-color); }
    }
```

--------------------------------

### Cache and Refresh Configuration

Source: https://context7.com/alexpfau/calendar-card-pro/llms.txt

Configure the polling interval and refresh behavior for the calendar card.

```yaml
type: custom:calendar-card-pro
entities:
  - calendar.family

# Polling interval in minutes (default 30)
refresh_interval: 15

# Force API refresh when navigating between dashboard views (default true)
refresh_on_navigate: false
```

--------------------------------

### Configure Week Numbers and Separators

Source: https://context7.com/alexpfau/calendar-card-pro/llms.txt

Control the display of week numbers using ISO or simple formats, set the first day of the week, and define the width and color of separators between days, weeks, and months.

```yaml
type: custom:calendar-card-pro
entities:
  - calendar.personal
days_to_show: 28

show_week_numbers: 'iso'        # 'iso' | 'simple' | null
show_current_week_number: true
first_day_of_week: 'monday'     # 'monday' | 'sunday' | 'system'
week_number_font_size: '12px'
week_number_color: 'var(--primary-text-color)'
week_number_background_color: '#03a9f450'

# Separators (precedence: month > week > day)
day_separator_width: '1px'
day_separator_color: '#03a9f430'
week_separator_width: '2px'
week_separator_color: '#03a9f450'
month_separator_width: '3px'
month_separator_color: '#03a9f4'
```

--------------------------------

### Navigate to Another View on Tap

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Configures a tap action to navigate to a different Lovelace view. Specify the desired path using `navigation_path`.

```yaml
tap_action:
  action: navigate
  navigation_path: /lovelace/calendar
```

--------------------------------

### Configure Base Date Column Appearance

Source: https://context7.com/alexpfau/calendar-card-pro/llms.txt

Set font sizes, colors, and visibility for month and day elements in the date column. Overrides for weekends and today are supported.

```yaml
weekday_font_size: '14px'
weekday_color: 'var(--primary-text-color)'
day_font_size: '26px'
day_color: 'var(--primary-text-color)'
show_month: true
month_font_size: '12px'
month_color: 'var(--primary-text-color)'
date_vertical_alignment: 'middle'  # 'top' | 'middle' | 'bottom'

# Weekend overrides
weekend_weekday_color: '#e67c73'
weekend_day_color: '#e67c73'
weekend_month_color: '#e67c73'

# Today overrides (takes precedence over weekend)
today_weekday_color: '#03a9f4'
today_day_color: '#03a9f4'
today_month_color: '#03a9f4'

# Today indicator
today_indicator: pulse             # true/dot | pulse | glow | mdi:star | 🎯 | /local/img.png
today_indicator_position: '15% 50%'  # x% y% within the date column
today_indicator_color: '#03a9f4'
today_indicator_size: '8px'
```

--------------------------------

### Multiple Calendars with Custom Styling

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Applies accent colors and background opacity for visual distinction between calendars. Configures event spacing and line width.

```yaml
type: custom:calendar-card-pro
entities:
  - entity: calendar.family
    accent_color: '#ff6c92'
  - entity: calendar.work
    accent_color: '#1e88e5'
  - entity: calendar.personal
    accent_color: '#43a047'
days_to_show: 5
compact_events_to_show: 5
event_background_opacity: 20
vertical_line_width: 5px
event_spacing: 6px
```

--------------------------------

### Configure Event Column Appearance

Source: https://context7.com/alexpfau/calendar-card-pro/llms.txt

Customize the display of time, location, description, and progress bars for events. Options include showing end times, 24-hour format, and limiting description lines.

```yaml
type: custom:calendar-card-pro
entities:
  - calendar.work

# Time
show_time: true
show_end_time: false
show_single_allday_time: false
time_24h: true          # false = 12h | 'system' = inherit HA setting
time_two_digit_hours: true   # Pad: 09:00 instead of 9:00
time_font_size: '12px'
time_color: 'var(--secondary-text-color)'
time_icon_size: '14px'

# Location
show_location: true
remove_location_country: 'USA|United States'  # RegExp, true, or false
location_font_size: '12px'
location_color: 'var(--secondary-text-color)'

# Description (v3.2+)
show_description: true
description_max_lines: 3    # 0 = unlimited; HTML stripped automatically
description_font_size: '12px'
description_color: 'var(--secondary-text-color)'
event_icon_vertical_alignment: 'top'  # 'top' | 'middle' | 'bottom'

# Countdown / progress bar (mutually exclusive per event)
show_countdown: true           # Shows "in 3 days" / "in 2 hours" for future events
show_progress_bar: true        # Shows completion % for running events
progress_bar_color: '#03a9f4'
progress_bar_height: '8px'
progress_bar_width: '80px'

# Past events (today only)
show_past_events: false        # true = show at 60% opacity
```

--------------------------------

### Enable Progress Bars for Running Events

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/RELEASE_NOTES.md

Show visual progress indicators for events currently in progress. Customize color, height, and width to match your theme.

```yaml
# Enable progress bars for running events
show_progress_bar: true
progress_bar_color: '#03a9f4'
progress_bar_height: '10px'
progress_bar_width: '60px'
```

--------------------------------

### Configure Event Description Display

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Control the visibility, maximum lines, font size, and color of event descriptions. Descriptions are automatically cleaned of HTML tags and decoded.

```yaml
# Description display options
show_description: true
description_max_lines: 3 # Limit to 3 lines (0 = unlimited)
description_font_size: '12px'
description_color: 'var(--secondary-text-color)'
description_icon_size: '14px'
```

--------------------------------

### Multiple Calendars with Week Numbers and Separators

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Enables week number display and visual separators for months and weeks. Customizes separator colors and widths.

```yaml
type: custom:calendar-card-pro
entities:
  - entity: calendar.personal
    accent_color: '#03a9f4'
  - entity: calendar.family
    accent_color: '#ff6c92'
days_to_show: 5
compact_events_to_show: 5
vertical_line_width: 5px
event_spacing: 5px
show_week_numbers: iso
week_separator_width: 1px
week_separator_color: '#03a9f450'
month_separator_width: 1.5px
month_separator_color: var(--secondary-text-color)
```

--------------------------------

### Mermaid Diagram for Module Interaction

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/architecture.md

Visualizes the relationships and data flow between different modules within the Calendar Card Pro.

```mermaid
graph TD
    Main[Calendar Card Pro Main] --> Config[Configuration]
    Main --> Events[Event Processing]
    Main --> Render[Rendering]
    Main --> State[State Management]
    Main --> Inter[Interactions]

    %% Configuration interactions
    Config --> Constants[Constants]
    Config --> Types[Type Definitions]

    %% Event processing flow
    Events --> Cache[LocalStorage Cache]
    Events --> API[Home Assistant API]
    Events --> Format[Formatting]

    %% Rendering flow
    Render --> DOM[DOM Operations]
    Render --> Styles[CSS Generation]
    Render --> Localize[Translations]

    %% Interaction flow
    Inter --> Actions[Action Handling]
    Inter --> Ripple[Ripple Effects]
    Inter --> Feedback[Visual Feedback]

    %% State management
    State --> Lifecycle[Component Lifecycle]
    State --> Refresh[Refresh Timer]
    State --> Visibility[Page Visibility]

    %% Cross-cutting concerns
    Logger[Logging System] --> Main
    Logger --> Events
    Logger --> Render
    Logger --> Inter
```

--------------------------------

### Configure Split Multi-Day Events

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/RELEASE_NOTES.md

Display multi-day events on each day they cover for better visibility. This can be enabled globally or controlled on a per-calendar basis.

```yaml
# Show multi-day events on every day they cover
split_multiday_events: true

# Control splitting on a per-calendar basis
entities:
  - entity: calendar.personal
    split_multiday_events: true
  - entity: calendar.work
    split_multiday_events: false
```

--------------------------------

### Call a Home Assistant Service

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Configures an action to call a specific Home Assistant service. Requires `service` and optionally `service_data` for parameters.

```yaml
action: call-service
service: domain.service
service_data: { key: value }
```

--------------------------------

### Configure Weather Integration

Source: https://context7.com/alexpfau/calendar-card-pro/llms.txt

Integrate weather forecasts into the date column, event rows, or both. Customize the display of conditions, temperatures, and UV index, including thresholds and icon sizes.

```yaml
type: custom:calendar-card-pro
entities:
  - calendar.family
days_to_show: 5

weather:
  entity: weather.forecast_home
  position: both          # 'date' | 'event' | 'both'

  date:
    show_conditions: true
    show_high_temp: true
    show_low_temp: true
    show_uv_index: true
    uv_index_threshold: 3   # Hide UV index below this value
    icon_size: '16px'
    font_size: '14px'
    color: '#3498db'

  event:
    show_conditions: true
    show_temp: true
    show_uv_index: false
    icon_size: '14px'
    font_size: '12px'
    color: 'var(--secondary-text-color)'
```

--------------------------------

### Configure Enhanced Compact Mode

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/RELEASE_NOTES.md

Gain precise control over the compact calendar view by limiting the number of days and events shown. Ensures complete days are always displayed.

```yaml
# Display fewer days in compact mode
compact_days_to_show: 2 # Show just 2 days in compact mode
days_to_show: 7 # Show full 7 days when expanded

# Limit events in compact mode
compact_events_to_show: 5 # Show only 5 events in compact mode

# Ensure complete days are shown
compact_events_complete_days: true # Never show partial days
```

--------------------------------

### Configure Event Appearance and Empty Days

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Customize the font size and color for event titles. Control the display of days with no events by setting `show_empty_days` and define the color for the 'No events' text.

```yaml
# Event title appearance
event_font_size: '14px'
event_color: 'var(--primary-text-color)'

# Empty days display
show_empty_days: true # Show days with no events
empty_day_color: 'var(--secondary-text-color)' # Color for "No events" text
```

--------------------------------

### Increment Version for Caching

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/CONTRIBUTING.md

Increment the version number in the resource URL to force Home Assistant to load the updated file.

```yaml
url: /hacsfiles/calendar-card-pro/calendar-card-pro-dev.js?v=2
type: module
```

--------------------------------

### Limit Events in Compact View

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Sets the maximum number of events to display in the compact view. An indicator appears if more events are available. Use with `tap_action: expand` to toggle between compact and full views.

```yaml
compact_events_to_show: 5
```

--------------------------------

### Style Today's Date

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/RELEASE_NOTES.md

Customize the appearance of today's date components individually. Undefined values inherit styling, and today's styling takes precedence on weekends.

```yaml
# Style today's date components individually
today_weekday_color: '#03a9f4' # Color for today's weekday name
today_day_color: '#03a9f4' # Color for today's day number
today_month_color: '#03a9f4' # Color for today's month name
```

--------------------------------

### Configure Today Indicator

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Enable and customize the indicator for the current day. Supports various types like dots, pulses, glows, icons, emojis, or custom images.

```yaml
# Enable and choose indicator type
today_indicator: true # Enable basic dot indicator (default)
today_indicator: pulse # Animated pulsing dot
today_indicator: glow # Glowing dot
today_indicator: mdi:star # Any Material Design icon
today_indicator: 🎯 # Emoji
today_indicator: /local/custom-indicator.png # Image path
```

--------------------------------

### Customize Calendar Labels with Icons and Images

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/RELEASE_NOTES.md

Enhance calendar labels using Material Design Icons (`mdi:icon-name`), custom images from the `/local/` directory, or standard emojis and text. The card automatically detects the format.

```yaml
entities:
  - entity: calendar.work
    label: '💻' # Original emoji style
  - entity: calendar.family
    label: 'mdi:account-group' # Material Design Icon
  - entity: calendar.vacation
    label: '/local/icons/beach.png' # Custom image
```

--------------------------------

### Configure Cache and Refresh Settings

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/README.md

Adjusts how often the card's data is refreshed and whether it should refresh when navigating between dashboard views. `refresh_interval` is in minutes.

```yaml
# Cache and refresh settings
refresh_interval: 30 # Minutes between data refresh
refresh_on_navigate: false # Keep cache when switching dashboard views
```

--------------------------------

### Customize Styling for Empty Days

Source: https://github.com/alexpfau/calendar-card-pro/blob/main/docs/RELEASE_NOTES.md

Set a custom color for days that have no events using the `empty_day_color` option. This allows for better visual distinction and theme integration.

```yaml
empty_day_color: '#ff5722' # Use custom color
```