Week Planner Card: a week of Home Assistant calendars on one dashboard

A Lovelace card that renders a week, not a list

The project describes itself as a custom Home Assistant card displaying a responsive overview of multiple days with events from one or multiple calendars, and the repository description says the same thing with the detail that the events come from one of multiple calendars.

That framing is worth holding on to, because Home Assistant already has a built-in calendar view and this card is not it. What this card does is draw a grid: columns are days, cells are events, and the whole thing is a single Lovelace card you place on a dashboard. The word responsive in the description matters for a wall-mounted tablet, which is where these cards usually end up, because the layout has to work whether the panel is narrow and tall or wide and short.

The repository topics describe the shape of the thing: calendar, home-assistant, homeassistant, homeassistant-custom-component, lovelace-card, lovelace-custom-card, planner and week-planner. The MIT licence is confirmed by the badge and by the `LICENSE` file in the tree, and the author is Rudy Gnodde.

The audience is a Home Assistant user who has already installed the platform, already has calendar integrations configured, and wants a denser view of the week than the default calendar card gives. It is a front end with no backend, no configuration file on the server and no data store of its own.

The last push to the default branch was on 2026-04-26, and the most recent releases are v1.14.1 and v1.14.0, both on 2026-01-25, with v1.13.1 on 2026-01-18. The repository is not archived.

Installing through HACS, or copying one file

The README gives two installation routes and calls the first one recommended.

The HACS route requires HACS to be installed and working, then you search for `week-planner-card` and download and install it using HACS. HACS is the Home Assistant community store, so this is the path that handles updates for you.

The manual route is two steps. You download and copy `week-planner-card.js` from the latest release into your `config/www` directory, and then you add a resource reference to the Home Assistant configuration. The README gives the YAML for the configuration file:

    resources:
      - url: /local/week-planner-card.js?version=1.14.1
    type: module

The `config/www` directory is what Home Assistant serves as `/local/`, which is why the URL in the resource entry is `/local/week-planner-card.js`. The `type: module` line is what tells Home Assistant to load it as a JavaScript module rather than a classic script, and it matters because the card is built as a module.

There is a graphical alternative to editing the YAML, and the README walks through it: enable advanced mode in your user profile, go to Settings and then Dashboards, click the three vertical dots in the top right corner and select Resources, click the Add resource button in the bottom right corner, enter the URL `/local/week-planner-card.js`, select type JavaScript Module, and restart Home Assistant.

Two details are easy to get wrong. The `?version=1.14.1` query string in the resource URL is how Home Assistant is told to bust its browser cache, and the value has to be bumped when you update the file or the old version keeps running from cache. And the restart at the end is not optional, because resources are read at startup.

The options table, and which ones earn their place

The configuration table is the substance of this project, and it carries a version column that tells you when each option appeared, which is unusually useful documentation.

The `type` option is required and must be `custom:week-planner-card`. The `title` option is optional and was added in 1.6.0. The `days` option is a number or a string, defaults to 7, and accepts any positive integer or the value `month`, and it was introduced in 1.0.0.

The two cap options came in 1.11.0. `maxEvents` limits the total number of events shown, with 0 meaning no maximum, and `maxDayEvents` does the same per day, also with 0 for no maximum. Together they let you bound a busy calendar without editing your event data.

The `startingDay` option, added in 1.2.0, is the one that makes this card different from a generic week view. It defaults to `today` and accepts `today`, `tomorrow`, `yesterday`, and each of the seven weekday names, plus `month`. So a card can start on Saturday, or on the current month rather than a rolling week. The `startingDayOffset` option, added in 1.7.0, adds or subtracts days from that starting day, and `hideWeekend`, also 1.2.0, drops Saturday and Sunday from the grid entirely.

The display options are mostly 1.0.0 era: `noCardBackground` removes the default card background and border, `eventBackground` sets the event background colour and defaults to `var(--card-background-color, inherit)`, and `compact` reduces several spacings and font sizes. The `updateInterval` option, also from 1.0.0, sets the number of seconds between checks for new events and defaults to 60.

That last default is a design choice with a consequence. A dashboard that refreshes every ten seconds still shows data that is at best a minute old, and the card does not read the Home Assistant event stream, it polls.

Calendars, texts, weather and the cardmod styling path

The table of contents lists three more configuration groups beyond the main options, and each one exists to solve a specific annoyance.

The calendars group is where you list the calendar entities to pull events from, and the description of the card says events come from one or multiple calendars, so the group is a list rather than a single value. The main options table marks `calendars` as required, in the same way `type` is required, which tells you the card will not render meaningfully without at least one entry.

The texts group is for the labels the card draws. A week planner has a lot of fixed words in it, day names, month names, and the labels for things like the more indicator, and putting them in a configuration group rather than hard-coding them is what makes the card usable in a language other than the one it was written in.

The weather group is the least obvious, and its presence says something about how the card is used. Putting weather next to a week of events is a planning decision: the card is meant to sit on a dashboard you look at in the morning, and knowing the forecast alongside the week's commitments is the point of combining them on one panel rather than two.

The README also has a section on custom styling using cardmod. Cardmod is a Home Assistant card modification tool that lets you apply styles to parts of a card, and the fact that this card documents a cardmod workflow rather than a set of its own style options tells you the project expects users to have that ecosystem installed and to reach for it when the built-in options are not enough.

The examples directory holds a single file, `examples/card.png`, which is the screenshot referenced from the README.

How the card is built, and where the dependencies come from

The packaging metadata shows a small and modern build, and the dependency list explains most of the card's behaviour.

The package is `week-planner-card` at version 1.14.1, with the source at `src/index.js` and the built module at `dist/week-planner-card.js`. The build uses Parcel, with a `watch` script running `parcel watch` and a `build` script running `parcel build`, and the module target is configured with `includeNodeModules: true` and `optimize: true`, which is why the shipped file is self-contained and can be dropped into `config/www` with no bundling step on the Home Assistant side.

The runtime dependencies are two: `lit` at 3.1.2 and `luxon` at 3.4.4. Lit is the web components library, so the card is built as a custom element using the standard lit model, which is why it can be loaded as a JavaScript module and why it participates in the same rendering model as the rest of a modern Home Assistant frontend. Luxon is the date and time library, and its presence is the explanation for the calendar handling: month names, day names, week arithmetic and the `month` value of the `days` option all need real date handling rather than string manipulation, and Luxon is the conventional choice for that inside a lit component.

The dev dependencies are Parcel itself at 2.16.3, the Parcel data URL optimizer and inline string transformer, and `svgo` at 3.3.2 for optimising SVG assets.

The `Makefile` wraps the npm workflow with an `install` target running `npm install` and a `build` target running `npm run build`, plus a `set-version` target that is more interesting than it looks. It takes a `VERSION` variable, validates that it matches the format `x.y.z` with a regular expression, then uses `sed` to rewrite the version in the `README.md` resource URL and runs `npm version` to update `package.json` and `package-lock.json`.

That target exists because the version string appears in three places at once, in the README, the manifest and the lock file, and the card is distributed as a file rather than as a package, so the version in the URL is the version a browser fetches. Getting that wrong is how a user ends up running a stale card after an update, and the Makefile makes the correct sequence a single command.

Where the Week Planner Card is the wrong tool

The first wrong-tool case is a need for the standard calendar view. If what you want is the familiar Home Assistant calendar card with a month grid and event popups, this is a different thing, and installing it does not improve the built-in one. It is a week-oriented grid and nothing else.

The second is a dashboard with no other cards. The value of this card is comparative: it sits next to a weather card, a todo card and a media card and gives the week in one block. On a dashboard with one card on it, the density is decoration.

The third is a requirement for many users or shared access. The card renders the events of the calendars you configure, and nothing in the documentation suggests per-user filtering, so a dashboard shared between household members shows the union of the configured calendars to everyone who can see the panel. For a shared wall tablet in a home with two people with separate calendars, that is a data exposure question rather than a feature question.

The fourth is an environment where you cannot place a file in `config/www` and edit the YAML configuration. The manual install requires both file system access to the Home Assistant configuration directory and a restart, and the HACS route assumes a working HACS installation. Both are normal for a self-hosted instance and both are obstacles in a managed or containerised setup where you only have the UI.

The alternative worth naming is the built-in Home Assistant calendar card, and the difference in approach is density against familiarity. The built-in card is the safe choice for a single calendar view with popups and a month grid, and it needs no extra file, no resource registration and no restart. The Week Planner Card trades that for a denser week layout, per-day event caps, a start day you choose, translatable labels and a cardmod styling path, which is the right trade for a planning panel and the wrong one for a general dashboard.

Maintenance state, the version column, and the licence

The maintenance picture is a bit mixed, and the version column in the options table is the tool for reading it.

Each option in the table carries the version that introduced it, running from 1.0.0 for the original options, through 1.2.0 for `startingDay` and `hideWeekend`, 1.6.0 for `title`, 1.7.0 for `startingDayOffset`, and 1.11.0 for `maxEvents` and `maxDayEvents`. That is a useful map of a project that grew by adding targeted features rather than by redesigning.

The releases are v1.14.1 and v1.14.0 on 2026-01-25 and v1.13.1 on 2026-01-18, with the last push to the default branch on 2026-04-26. So the code has moved since the newest tag, and the tagged versions are from January 2026. The repository is not archived, and the README carries a buy me a tea badge for the author, which is how this kind of single-maintainer project funds itself.

The licence is MIT, with a `LICENSE` file in the tree, and the `hacs.json` file at the top level is what makes the project installable through HACS, since that file is the store metadata. The `Makefile` also has a `help` target that parses its own comment headers to print the available targets, a small touch that makes the file self-documenting for anyone who lands in the repository without reading the README.

The practical note for an adopter is the version string. Because the card ships as a JavaScript file that you host yourself, and the README tells you to add a `?version=` query string to the resource URL, upgrading means copying the new file, bumping that query string and restarting Home Assistant. The `set-version` target in the Makefile handles the string, but the copy and the restart are still yours.

Editorial conclusion

Adopt the Week Planner Card when your Home Assistant dashboard needs a week of calendar events visible at once, especially when the week does not start on Monday, since the `startingDay` option accepts every weekday name as well as `month`. Do not adopt it if you need events to appear in the standard Home Assistant calendar view, since this card only renders its own grid, and remember that the update interval defaults to 60 seconds, so a dashboard refreshing more aggressively still sees the same data. Before you install, pick your installation route, since HACS and the manual copy produce the same file, and check the version column of the options table against the release you are installing, because the URL resource reference in your configuration includes an explicit version query string that has to match.

Frequently asked questions

Official sources

1. FamousWolf/week-planner-card on GitHub
2. Issues
3. License: MIT
4. README
5. Releases