Calendar Card

Features

• Two cards: calendar-agenda-card and its mini version calendar-agenda-mini-card (next event and the one after; a detail button unfolds the full agenda)
• Several calendars merged in one list, each with its own color and name; an event shared by several calendars (same uid) is listed once, distinct events with the same title and times are all kept
• Days with today and tomorrow labelled, all-day events, time range and location; a multi-day event is listed once with its date range
• Countdown for today's events (in 25 min, in 2 h 05), Now badge and progress bar for the event under way; finished events go away
• Week view (view: week): the 7 days from today side by side, each event a tile in its calendar's color (time and title); one day per row on a narrow card; arrows (or a swipe) to the previous or next week, and Today to come back
• Events past max_events fold into a N more events section (chevron right folded, down unfolded, folds back on a click elsewhere)
• Click an event for its details (date and time, location, calendar, description) in a popup at the top of the card; the keyboard focus moves into the popup or the form and back to the event when it closes
• + button in the header: a New event form (title, calendar, all day, start and end date and time, location, description) adds the event to a calendar that accepts new events (local calendar, CalDAV, Google…); the end date allows overnight and multi-day events
• Edit and Delete buttons in the event details, for a calendar that allows it: edit opens the same form pre-filled, delete asks for a confirmation in the popup; for a recurring event, the change applies to this event only or to this one and the following ones
• Hide events by title with exclude
• Refreshes when an event starts or ends and every 5 minutes
• Visual editor in the dashboard UI
• English, French, German, Spanish, Serbian (Cyrillic and Latin), Italian, Dutch, European Portuguese, Polish, Romanian, Danish, Swedish, Bulgarian, Russian, Ukrainian, Hungarian, Slovak, Czech, Slovenian, Latvian and Greek, follows the Home Assistant language, 12 h / 24 h time format and time zone setting (the browser's or the server's)
• Light and dark theme compatible
• Single file, no dependencies, ready for the Marketplace

Prerequisites

• Home Assistant 2024.8 or later with at least one calendar.* entity

Configuration

Visual editor#

Add the card from the dashboard (Add card → Calendar Agenda Card or Calendar Agenda Mini Card). The first calendars found are picked; change them with the Calendars field, then set the title, the number of days and the sections to show. Colors and names per calendar are set in YAML; the editor keeps them. Options left at their default are not written to the YAML.

Minimal#

type: custom:calendar-agenda-card
entities:
  - calendar.home
  - calendar.work

Mini card#

type: custom:calendar-agenda-mini-card
entities:
  - calendar.home
  - calendar.work

The mini card shows today's all-day events under way (school holidays, a public holiday…) on a compact line each, with the day they end, then the event under way or the next one (with its countdown), then the one after. A click (or Enter) on any of these lines opens the event's details. The detail button (top right) unfolds the full agenda; a click anywhere else on the page folds it back. It takes the same options as the full card, which apply once unfolded, plus zoom.

Full options#

type: custom:calendar-agenda-card
title: Family
entities:
  - entity: calendar.home
    color: "#039be5"
    name: Home
  - entity: calendar.work
    color: "#33b679"
  - entity: calendar.public_holidays
    color: "#8e24aa"
    name: Holidays
view: agenda
days_to_show: 7
max_events: 5
show_header: true
show_location: true
show_end_time: true
show_countdown: true
show_empty_days: false
show_past_events: false
exclude:
  - Private
language: en

Options reference#

Calendar options:

How it works

The card asks Home Assistant for the events of each calendar between today midnight and days_to_show days later (the /api/calendars/<entity> endpoint the built-in calendar uses). It fetches again when a calendar entity changes state (an event starts or ends), when the day changes and every 5 minutes; countdowns move on every minute. A calendar that fails to load is named under the list and the others are still shown.

Times follow the Time zone setting of the Home Assistant user profile: the browser's zone by default, or the server's zone (hass.config.time_zone) when the profile is set to use it. The days, the times and the event form all use that zone.

The + button appears when at least one calendar supports creating events. The form needs a title, a date and, unless all day, a start and an end time. It calls the calendar.create_event action (all-day events end the next day, as Home Assistant expects) and the agenda fetches again once it is saved; an error from the calendar is shown in the form.

The Edit and Delete buttons appear in the details of an event that has a uid, when its calendar supports updating or deleting events. They use the calendar/event/update and calendar/event/delete WebSocket commands, like the calendar panel of Home Assistant: times are sent in UTC, all-day events as dates ending the next day, the description edited in the form like the other fields. For a recurring event, the card asks whether the change applies to this event only or to this one and the following ones (recurrence_range: THISANDFUTURE, the recurrence rule kept). The agenda fetches again once the event is saved or deleted; an error is shown in the form or the popup.

A multi-day event is listed once, on the first day shown (its start day, or today when it started earlier), with its date range. Today's timed events that are over are hidden unless show_past_events is on.

Support

If you find this project useful, you can support its development:

Features

• show_title option (also in the visual editor) hides the header's title, keeping its date and today's count, for a card placed under a section heading of its own (asked in juju35/ha-vehicle-card#72).

Improvements

• Week view: arrows to show the previous or the next week, its dates between them, and Today to come back; a horizontal swipe over the days does the same on a phone. A past week shows its past events.

Maintenance

• No code change: released again to check the installation from the Marketplace.

Features

• Week view (view: week, View in the editor): the full card lays the 7 days from today side by side, today highlighted, each event a tile in its calendar's color with its start time (or All day) and title; a click opens its details as in the list. Under 504 px wide, one day per row. The mini card keeps its list. 22 languages.

Fixes

• Translations: the cards are defined once the page's language file has arrived (at most 1.5 s; Home Assistant builds a card when its element gets defined), so the first render is already translated instead of English then redrawn; until a language file is in, a missing text reads the English one wherever the card has no fallback of its own.

Performance

• Translations load on demand: the bundle keeps English only (133 KB → 82 KB) and each other language is its own calendar-card.i18n.<lang>.js file next to it, fetched the first time a card needs it. Home Assistant loads every dashboard resource on every dashboard, so each page used to download and parse all 22 languages to use one. Until a language file has arrived (a few milliseconds), texts fall back to English, and the cards redraw once it is there.

Maintenance

• Build: scripts/i18n-split.mjs splits the built bundle and rebuilds every table from the split files to check them (the build fails on any difference); src/ keeps every language as before.
• Release: every file of dist/ is attached. Manual installation copies the translation files too.