HTML Action Card: one Home Assistant card for every design
It started with a camera. My Tapo C200 exposes four “move” buttons in Home Assistant, and I wanted a small joystick on my dashboard to steer it. Not difficult in principle. In practice it meant searching for yet another custom card, learning its YAML options, and accepting whatever it looked like.
That happens again and again with Home Assistant dashboards. Every new look means another custom card with its own configuration language. The cards are good, but the design is always someone else’s.
So I built the opposite: one card where you write plain HTML and CSS, and connect it to Home Assistant with a handful of attributes.
Video: the cards running in Home Assistant
Four building blocks
The whole card is one field of HTML. Four small building blocks connect it to the house:
<button data-event="tap" data-action="light.toggle" data-entity="light.kitchen">
Kitchen: {{ light.kitchen.state }}
</button>
<p data-show-if="sensor.temperature.state > 25">It's warm in here</p>{{ … }}inserts a live value, in text and in attributes such asclassorstyle.data-show-ifshows an element only while a condition holds.data-actionsays what happens: any service, a toggle, the more-info dialog, a navigation.data-eventsays when: tap, hold, double tap, press with repeat, release.
Anything the four blocks cannot express goes into an optional <script> block, which receives a small card API to call services, read states and react to changes.
Keeping it live without a framework
Home Assistant hands every card a new hass object whenever any entity changes, which can be many times per second. Re-rendering the whole card each time would be wasteful and would reset everything a user is interacting with.
The card therefore tracks dependencies. Every expression is evaluated through a resolver that records which entities it reads. When a new hass object arrives, only those entities are compared, and only by reference: Home Assistant replaces a state object when it changes, so an unchanged entity is the very same object. Affected expressions are re-evaluated, their dependencies recorded again (an a && b may read b only sometimes), and the DOM is written only when the result actually changed.
The expressions themselves run through a small parser and evaluator of their own. No eval, no new Function for user expressions, and a bare light.kitchen deliberately renders nothing: like in Home Assistant templates, you always name the property (.state, .attributes.brightness).
Scripts that clean up after themselves
Scripts are where custom UI code usually leaks. Home Assistant detaches and re-attaches cards often, for example while you edit a dashboard. A script that adds a window listener or starts a timer would pile them up each time.
Each card’s scripts get their own setTimeout, setInterval, requestAnimationFrame, window and document listeners and observers, all registered in one place and released when the card goes away. After teardown nothing can register any more, even from a promise that resolves late. The script code stays plain JavaScript; it does not need to know.
A rating instead of a sandbox
The obvious objection to “paste any HTML”: what about code from the internet, or from an AI?
I decided against a sanitizer that silently removes things. A framework that rewrites your code behind your back is hard to trust and hard to debug. Instead, the card editor analyses every card while you type and rates it:
- green: plain markup, styles and building blocks
- yellow: scripts, external resources, or a sensitive action such as a lock without a confirmation
- red: things that can run or load foreign code or reach credentials, such as iframes, external scripts,
eval, network or storage access
Every finding names the line. Nothing is blocked; you decide, but you decide knowing what the code does.
Cards that can be shared
To make cards reusable, a card can start with a small YAML frontmatter, just like a Home Assistant blueprint:
---
name: Lamp switch
inputs:
lamp:
name: Lamp
selector:
entity:
domain: light
---The editor turns that into a form with Home Assistant’s own entity pickers. Someone else can paste the card and pick their own lamp, without touching the code.
What it makes possible
The showroom in the repository shows where this gets interesting, with things that would need a dedicated custom card each:
- a turntable for any media player: the album cover spins on the record, the vinyl takes on the cover’s colour, the tone arm follows the song and can be dragged to seek
- a pull-cord lamp: pull the cord, the light switches, the cord springs back and the lamp swings
- a camera control where the live picture itself is the joystick
- a kitchen timer, a panda that follows your cursor, and Snake
Made for the AI era
AI assistants are very good at HTML and CSS and rather bad at remembering the options of a specific custom card. HTML Action Card plays to that strength: describe the card you want, paste the result, and let the rating show what it does. The repository contains a ready-made prompt for exactly that.
How it was built
The idea, the concept and the product decisions are mine; the implementation was done together with Claude Code, Anthropic’s coding assistant, including the expression parser, the dependency tracking, the analyzer and around 260 automated tests. It was a good example of what that kind of collaboration can do when the direction is clear.
Try it
HTML Action Card is open source under the MIT license and installs through HACS as a custom repository (type Dashboard).
- Repository: github.com/davidrot/ha-html-action-card
If you build a card with it, I’d love to see it in the showroom.