Calendar Card Pro: a Home Assistant calendar card built for speed

It exists because button-card and card-mod were slow

Calendar Card Pro is a dedicated Lovelace card for Home Assistant, and the README explains where the idea came from. It was inspired by a calendar design that used button-card and the Hass calendar add-on, shared in the Home Assistant community. The design was visually good, but implementing it with button-card and card-mod led to performance issues.

That is the origin story and the design constraint in one sentence. The card's stated purpose is to excel in one thing, displaying upcoming events beautifully and efficiently.

The performance claims are specific in kind rather than in numbers. The card is described as leveraging intelligent refresh mechanisms and smart caching, with the feature list naming smart caching, progressive rendering and minimal API calls, and the overview saying this keeps the experience smooth even when multiple calendars are in use. There is no benchmark table in the documentation, so the claim to hold onto is the mechanism rather than a figure: the card decides when to refresh and what to cache, instead of letting the dashboard re-render everything.

The rest of the feature list is broader. Multi-calendar support with unique styling per calendar, compact and expandable views, a visual configuration editor, fine tuning of layout, colours, event details and behaviour, weather forecasts shown alongside events, theme awareness with native ripple effects, and multi-language support in 35 languages with community contributions welcome.

Two files, one of which you never name

The manual install is where most first-time users of a Home Assistant custom card go wrong, and this project explains it in more detail than most.

The card ships as two files, calendar-card-pro.js and editor.js, and both must sit in the same folder under www. The reason to use a subfolder rather than dropping them straight into /config/www/ is spelled out: that folder is shared by every hand-installed card, and editor.js is a common enough name that another file can take it.

The second detail is the one that catches people. Only calendar-card-pro.js is named as a resource, because the card loads the editor itself when you open it. The resource entry in your Lovelace configuration is:

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

The type is module, which matters for a modern browser and for how the card registers itself with Home Assistant. After that you clear the browser cache and refresh, and the card appears in the Add Card picker.

The HACS route is the recommended one and it handles all of this for you. HACS stands for Home Assistant Community Store, and the steps are to install HACS, go to HACS then Frontend then Custom Repositories, add the repository URL as type Dashboard, install the card, then clear the browser cache and reload. The repository type matters, because HACS uses it to decide how the card is presented.

The card needs a calendar entity before it needs a configuration

The dependency section is short and it is the first thing to check before anything else. Calendar Card Pro requires at least one calendar entity in Home Assistant, and it is compatible with any integration that generates calendar.* entities, with CalDAV and Google Calendar named as the primary tested integrations. The README marks this as important and says to make sure at least one calendar integration is set up before using the card.

That constraint is what makes the card generic rather than tied to one provider. Because it consumes the calendar.* entity interface, the same card works whether the events come from a local CalDAV server, a Google account or anything else Home Assistant exposes through that interface. The cost is that a user with no calendar at all gets nothing, and the visual editor will have nothing to point at.

The quick start is a dashboard operation rather than a configuration file edit. You add the card from the Add Card picker, search for Calendar, then use the three dots menu and Configure to open the visual editor. The README also documents a shortcut for Home Assistant 2026.6 and later, where switching to the By entity tab in the card picker and choosing any calendar.* entity offers Calendar Card Pro under Community, already pointed at the right entity.

That shortcut is a small but meaningful sign of integration: the card is discoverable through Home Assistant's own entity picker rather than only through a name search.

The documentation site carries the reference, not the README

The README is explicit that it is a starting point rather than the manual. It covers installation and a quick start, and everything else, every configuration option, all features and worked examples, lives on the documentation site at calendar-card-pro.alexpfau.com, which the README says is searchable and always matches the latest release.

The site is organised into an installation guide covering HACS or manual setup, a usage guide for adding the card and configuring it visually, a features and configuration section covering weather, templates, layout and actions, a complete configuration reference for every option, a set of ready-made example configurations to copy, and the full release notes for every release.

That structure is worth noting because a Home Assistant card can have a very large option surface, and a documentation site that is regenerated per release removes the drift problem where the README and the code disagree. The stated claim is that the site always matches the latest release, and the repository carries scripts that suggest this is enforced rather than hoped for.

The build tooling in the package manifest backs that up. There are check scripts for the internationalisation files, the documentation and the bundle itself, run as node scripts/check-i18n.mjs, node scripts/check-docs.mjs and node scripts/check-bundle.mjs. A docs check script is unusual and it tells you the documentation is part of the definition of done rather than a separate chore.

A TypeScript card with tests, i18n checks and a bundle check

The package manifest describes a conventional modern front end project, and the scripts are the clearest view of the workflow.

The build is Rollup with TypeScript, and the dev script runs rollup -c --watch while the build script runs rollup -c with NODE_ENV set to prod through cross-env. The package main is dist/calendar-card-pro.js. Linting is eslint across the source, test and script files, formatting is Prettier with a check mode, and the test suite is vitest.

The dependency list is all development dependencies, which is the point of a card that ships as a single JavaScript file with no runtime dependencies. The build toolchain includes the Rollup plugins for TypeScript, commonjs, node-resolve, json, replace and terser, plus esbuild, eslint 10 with the TypeScript and import plugins, Prettier and VitePress for the documentation site.

The documentation site has its own scripts, docs:dev, docs:build and docs:preview, all through VitePress. So the docs are a static site built from the same repository, which is how the site stays in step with the release.

There is also a wrangler.jsonc at the top level and a.node-version and.nvmrc, which pin the Node version used for the build. Combined with the check scripts and the pinned Node version, this is a repository that takes release hygiene seriously, and the MIT licence plus the NOTICE file at the top level are the other half of that picture.

Release pace and what to check after installing

The release history is steady and the project is being maintained right now. v4.2.0 was published on 2026-09-12, v4.1.0 on 2026-09-02 and v4.0.0 on 2026-08-18, and the last push to the main branch was on 2026-10-18.

The cadence is worth reading as a signal. Three tagged releases inside a month, and a major version bump in the same window, means the option surface is still moving. That has a practical consequence for a dashboard user: a configuration that worked in the 3.x line may not behave identically in the 4.x line, and the release notes page on the documentation site is where you would look for what changed.

Two practical checks after installing. The first is the browser cache, which the README mentions in both install routes, because Home Assistant will keep serving the old JavaScript file otherwise and the card will appear not to update. The second is the entity list: open the card and confirm that your calendar events are actually arriving, since an empty card is far more often a missing or unconfigured calendar.* entity than a rendering fault.

The project is MIT licensed with the licence file at the top level, the author is Alex Pfau, and the homepage doubles as the documentation site. Support runs through a Buy Me a Coffee link and GitHub Sponsors, so the funding model is voluntary sponsorship of a component that many people will run on their own dashboards for years.

Editorial conclusion

Adopt Calendar Card Pro when a Home Assistant dashboard shows calendar events and the existing card composition is dragging the frontend down, since the card exists because button-card and card-mod made that design slow, and the caching and progressive rendering are the reason it is faster. Do not adopt it without a calendar entity, because the card requires at least one calendar.* entity and works with any integration that produces one. Before you install, read the documentation site rather than the README, because the README says the configuration reference and every worked example live there, and decide between HACS and the manual route, since the manual route needs two files in the same www subfolder and only one of them is registered as a resource.

Frequently asked questions

Official sources

1. alexpfau/calendar-card-pro on GitHub
2. License: MIT
3. Project website
4. README
5. Releases