DOCSEARCHbyAlgolia
Submit Docs

Calendar Card Pro Documentation

repository·main·Indexed 22 days ago

https://github.com/alexpfau/calendar-card-pro

A high-performance, customizable calendar dashboard card for Home Assistant designed to replace heavy implementations with an optimized solution featuring smart caching and a visual configuration editor. It supports multi-calendar entities, weather integration, adaptive views, and localization in 33 languages. Compatible with any integration providing calendar.* entities, such as Google Calendar and CalDAV.

Tokens
19K
Snippets
46
Records
80
Agent score
76%

What's inside Calendar Card Pro

  1. Overview of Calendar Card Pro features

    main

    Calendar Card Pro is a high-performance Home Assistant dashboard card designed to display upcoming events beautifully and efficiently. Unlike implementations using button-card and card-mod, this dedicated card uses intelligent refresh mechanisms and smart caching to minimize API calls and ensure smooth performance.

    Key Capabilities:

    • Multi-Calendar Support: Display and style multiple calendar.* entities uniquely.
    • Adaptive Views: Switch between compact and expanded views.
    • Weather Integration: Show weather forecasts alongside calendar events.
    • Visual Configuration: Includes a built-in visual editor for easy setup.
    • Customization: Extensive control over colors, layouts, event details, and more.
    • Localization: Supports 33 languages.

  2. How user interactions are processed

    main

    User interactions follow a two-step flow:

    1. Input Capture: Pointer events (mouse/touch) and keyboard navigation are captured by the main component. The system includes hold detection with visual feedback.
    2. Action Execution: The actions.ts module processes the captured input to execute specific tasks such as expansion toggles, navigation, or Home Assistant service calls.

  3. Requirements and Dependencies

    main

    To use Calendar Card Pro, you must have at least one calendar entity configured in Home Assistant.

    It is compatible with any integration that provides calendar.* entities. The developers primarily test with:

    • CalDAV
    • Google Calendar

  4. Understand the Calendar Card Pro architecture

    main

    Calendar Card Pro is built as a modular LitElement-based web component designed for Home Assistant. The architecture separates concerns into several distinct modules:

    • Main Component (calendar-card-pro.ts): The central orchestrator managing lifecycle, reactive properties, state (loading, expanded, events), and coordination between all other modules.
    • Configuration (config/): Handles DEFAULT_CONFIG, normalization of entity configurations, and detects changes that trigger data refreshes.
    • Interaction (interaction/): Manages user input (tap, hold, keyboard) and provides visual feedback like ripples and hold indicators.
    • Rendering (rendering/): Uses pure functions and lit-html to generate the DOM, including the card editor and dynamic CSS styles.
    • Translations (translations/): Provides internationalization (33 languages) and locale-specific date formatting.
    • Utilities (utils/): Core logic for fetching/caching calendar events, date/text formatting, color manipulation, and logging.

  5. Performance and UX optimizations in Calendar Card Pro

    main

    The project implements several optimizations to maintain a smooth experience in Home Assistant:

    Performance Optimizations:

    • Smart Caching: Uses deterministic cache keys and configurable lifetimes for event data.
    • Efficient Rendering: Employs pure rendering functions and a stable DOM structure (compatible with card-mod) using lit-html for optimized updates.
    • Resource Management: Ensures proper cleanup of event listeners, timers, and component disconnection.

    UX Optimizations:

    • Progressive Loading: Provides clean loading states during data fetching.
    • Adaptive Display: Supports compact and expanded view modes and handles empty states gracefully.
    • Visual Feedback: Includes material ripple effects, hold indicators, and focus states for keyboard navigation.

  6. Understand smart event formatting

    main

    The card automatically adapts how events are displayed based on their properties:

    • All-Day Events: Special handling for both single-day and multi-day all-day events.
    • Ongoing Events: Multi-day events display status indicators like "Ends today" or "Ends tomorrow".
    • Past Events: Events that have already ended receive distinct visual styling.
    • Location Processing: Location strings are processed to remove country information for cleaner display.

  7. How smart caching works

    main

    The card uses a multi-level caching strategy to optimize performance and reduce API calls:

    • Event Data Caching: Calendar events are stored in localStorage. The cache key is deterministic, incorporating entities, days_to_show, past_events setting, and start_date.
    • Cache Invalidation: The cache is automatically invalidated when the configuration changes. The refresh frequency is controlled by the refresh_interval setting.
    • Deterministic IDs: Each card instance generates a stable ID based on its configuration. This ensures that multiple calendar cards on the same page do not conflict in the cache.
    • Intelligent Refresh: Refreshes are reactive to page visibility changes and Home Assistant reconnection events. Manual refreshes are rate-limited to prevent API abuse.

  8. How event data flows through the card

    main

    The card follows a specific lifecycle for managing and displaying calendar data to ensure performance:

    1. Initial Load: The component calls updateEvents(). The events.ts utility generates a cache key based on configured entities. It checks LocalStorage first; the Home Assistant API is only called if the cache is missing or expired.
    2. Data Processing: Raw events are filtered for relevant dates, grouped by day using groupEventsByDay(), and enhanced with formatted time and location strings. Entity-specific styling is then applied.
    3. Rendering: The main component triggers render(), which uses the Render module to build the DOM with dynamic styles and appropriate CSS classes for loading, error, or empty states.
    4. Refresh Mechanisms: Data is refreshed automatically via the refresh_interval config, manually when page visibility changes, or forced when the configuration is updated.

  9. Install Calendar Card Pro via HACS

    main

    The recommended method for installing Calendar Card Pro is through the Home Assistant Community Store (HACS).

    Steps:

    1. Ensure HACS is installed in your Home Assistant instance.
    2. Navigate to HACS → Frontend → Custom Repositories.
    3. Add the following repository URL as type Dashboard: https://github.com/alexpfau/calendar-card-pro
    4. Install Calendar Card Pro from the HACS interface.
    5. Clear your browser cache and reload Home Assistant to complete the installation.
    https://github.com/alexpfau/calendar-card-pro

  10. Install Calendar Card Pro manually

    main

    If you prefer not to use HACS, you can install the card manually by placing the JavaScript file in your Home Assistant www directory and registering it as a dashboard resource.

    Steps:

    1. Download the latest calendar-card-pro.js from the GitHub Releases page.
    2. Move the file to your Home Assistant /config/www/ folder.
    3. In Home Assistant, go to Settings → Dashboards → Resources → Add Resource.
    4. Register the resource with the following configuration:
    5. Clear your browser cache and refresh your browser.
    url: /local/calendar-card-pro.js
type: module

  11. Customize Calendar Card Pro with card-mod

    main
    The card supports card-mod for deep CSS customization and integrates with Home Assistant themes using standard CSS variables. You can target specific elements like headers, event titles, and containers to match your dashboard design.

  12. Customize Calendar Card Pro via Visual Editor or YAML

    main

    You can customize the appearance and behavior of the card using two methods:

    Visual Editor (Recommended)

    • Use the built-in visual configuration interface for an intuitive experience.
    • Changes are previewed in real-time.
    • Includes smart validation to prevent configuration errors.
    • Note: The visual editor is currently available in 8 languages, though the calendar itself supports 33 languages.

    YAML Configuration (Advanced)

    • Use YAML for advanced customization or when integrating with Home Assistant automations.
    • Refer to the Configuration Variables section of the documentation for the full list of supported keys and options.