Skip to content

Entity Progress Card logoEntity Progress Card logo

Lovelace Entity Progress Card

Home Assistant Marketplace HACS Custom Latest stable release License Documentation Docs (main) Discord

A progress bar card for Home Assistant: a battery, a washing machine cycle or a tank level, shown as a bar with its color and icon.

A dashboard of Entity Progress Cards: room temperature, fan, light, batteries, energy, printer ink, washing machine and moreA dashboard of Entity Progress Cards: room temperature, fan, light, batteries, energy, printer ink, washing machine and more

Thousands of Home Assistant dashboards run this card, every day: on a wall-mounted tablet, a phone, a screen that never turns off. Read at a glance, from across the room.

Add an entity and it's done: the right unit, the right icon, the right math, no YAML. Want more? The Template variants take a Jinja template in every field.

Not another progress bar: the one that disappears, because it simply does what it's supposed to.

🚀 Features

  • 7 variants, one card: a dashboard card, a compact badge, a Tile feature, or several bars stacked into one; most options carry over between them.
  • Visual editor: every variant has one, styled like Home Assistant's own. No YAML needed to get started.
  • Suggested for you: in Home Assistant's entity-first card picker (2026.6+), pick a sensor, light, cover, fan or timer, and the card is offered, already filled in.
  • Sensible defaults: the unit, icon and percentage come from the entity itself, before you change anything.
  • Visual effects: shimmer, glass, water, rainbow or segmented bars, your own color zones, and icons that move with the entity's state, with no card_mod (bar_effect, custom_theme, icon_animation). Each one has a screenshot in the Cookbook.
  • Alerts: past a threshold, the card glows, tints its background or shows a status pill (alert_when).
  • Reference lines: a mark at a low or high threshold, from a fixed value, another entity or a template (watermark).
  • History: an ↑/↓ arrow from the real trend, and the lowest, highest and average values marked on the bar (trend_indicator, peak_marker).
  • Templates: the Template variants compute the percentage, color, icon and text with Jinja, Home Assistant's template language, without a helper sensor.
  • Styling: every color, spacing and animation is a documented CSS variable, to set from your Home Assistant theme or card_mod (Theme Guide).
  • Accessible: screen readers announce the value, and motion stops when your device asks for reduced motion (details).
  • 41 languages: the editor and the card's messages follow your Home Assistant language (list).

📦 Installation

Requires Home Assistant 2024.0 or newer. The Home Assistant app and any recent browser work; for an older tablet or wall panel, check the table below.

Browser compatibility (click to expand)
HA
Home Assistant
Chrome
Chrome
Edge
Edge
Firefox
Firefox
Safari
Safari
Opera
Opera
Works 2024.0+ 98+ 98+ 94+ 15.4+ 84+
Full visual effects 111+ 111+ 113+ 16.2+ 97+

Ensure your Home Assistant instance is up to date to support this custom card.

The first row is the functional minimum — the card loads and works. A handful of purely decorative touches (a soft tint behind icons, the pulsing alert/ping animations, the bar's gradient sheen) need the newer "Full visual effects" versions and gracefully degrade below that: same information, just a little less vivid. See the live degraded-mode comparison for exactly what's affected.

I'm aware upgrading an embedded/kiosk device (a wall-mounted control panel in particular, e.g. an older Chromium like Chrome 92 — see issue #128) isn't always simple, so this is a deliberate, pragmatic trade-off rather than an oversight: full functionality first, full polish where the browser allows it.

entity-progress-card is available in HACS (Home Assistant Community Store). Since Home Assistant 2026.11, HACS is built in as the Marketplace: the steps below stay the same, under Marketplace.

Use this link to go directly to the repository in HACS or the Marketplace:

Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.

Or, step by step:

  1. Open HACS (called Marketplace from Home Assistant 2026.11). No HACS yet? Install it first.
  2. Look up Entity Progress Card.
  3. Click Download, then refresh the page (on a tablet: close and reopen the app).
Manual Installation (click to expand)

Download entity-progress-card.js from the latest release into /config/www/, then declare it as a resource:

  • Turn on Advanced mode in your user profile if Resources is missing.
  • Go to Settings ➡️ Dashboards, open the three-dot menu (⋮) at the top right, then Resources ➡️ Add resource
  • URL: /local/entity-progress-card.js
  • Type: JavaScript Module
  • Save, then reload the page (CTRL + F5 on a computer; on a tablet, close and reopen the app)

Note

The release also carries the visual editor, entity-progress-card-editor.js, and one entity-progress-card-<lang>.json file per language. Copy the editor and the language file you need — or all of them — next to the .js file: without the editor, Home Assistant offers its YAML editor instead; without the language file, the visual editor falls back to English. The cards themselves work and stay translated either way, and HACS (or the Marketplace) brings these files down for you. No extra resource is needed: the card loads them from its own folder.

📝 Usage

Two ways in: pick the entity and let the card fill itself in, or write the YAML.

From the card picker

Home Assistant 2026.6 or newer. On an older version, go to In YAML.

  1. Open Home Assistant's native "Add Card" picker and search for your entity.

    Entity-first card pickerEntity-first card picker

    Example: a light. Type its name and pick it: the bar shows its brightness, from 0 to 100 %.

  2. Click Entity Progress Card — it's already there, pre-filled.

  3. Fine-tune it in the visual editor: every option gets its own field, styled straight from Home Assistant's own design tokens.

    Show a screenshot of the visual editor

    EditorEditor

In YAML

Open your dashboard, select Edit dashboard, then Add card and Manual. Paste this with your own entity ID (Settings ➡️ Devices & services ➡️ Entities), then Save:

type: custom:entity-progress-card
entity: sensor.washing_machine_progress
name: Washing Machine
icon: mdi:washing-machine

Want the bar to turn red when a battery runs low (under 10 %)? One line does it:

Bars at 25, 50, 75 and 95 %: yellow, green, green, greenBars at 25, 50, 75 and 95 %: yellow, green, green, green

type: custom:entity-progress-card
entity: sensor.phone_battery_level
theme: critical_when_low

Your own limit, red under 20 %? Set your zones with a custom theme. A battery you charge? theme: battery_adaptive also warns when it stays near 100 % on the charger. Every theme, with its colors, is in the Theme Guide.

Colors, bar styles, alerts: most options work across all 7 variants — Card, Template Card, Badge, Badge Template, Tile Feature, Multi-Card, Multi-Feature. The option map shows which ones each accepts.

📚 Guides

That's enough to get started. Past that, here's where the rest of the depth lives — pick whichever guide matches what you're trying to do:

Guide What's in it
🍳 Cookbook Ready-made recipes (washing machine brands, an SSL countdown, a sun-tracking bar), a screenshot of every visual effect, and each variant's options at a glance
🎨 Theme Guide All 12 built-in themes with their exact value ranges, the full --epb-* CSS API, and the DOM reference for card_mod/UI-X styling
📖 Full Configuration Reference Every option, every variant — type, default, and a working example
🗺️ Option map Which options each of the 7 variants accepts, in one table

These guides describe the latest stable release. Testing a release candidate, or using an older release? Open the repository on GitHub and pick its tag.

🚨 Errors, Deprecations & Troubleshooting

A card showing a message is not broken, and nothing in your Home Assistant has changed: often, an entity is just offline.

♿ Accessibility

The card is designed to work well for everyone, out of the box.

Details (click to expand)
  • Screen readers: the progress bar exposes proper ARIA semantics (role="progressbar" with live aria-valuenow, including negative ranges in center_zero mode). Purely decorative elements (fill layers, watermarks, icon shape) are hidden from assistive technologies, so the card is announced once, with the right value — not as a pile of divs.
  • Reduce Motion: the card respects the system-level "Reduce Motion" setting (iOS/macOS, Android, Windows). When enabled, bar transitions and shimmer animations are disabled automatically to prevent dizziness, migraines or distraction.
  • Manual control: animations can also be tuned or disabled per card or per theme through the CSS API — e.g. --epb-progress-transition: none (see the Theme Guide).
  • Interactions: tap, hold and double-tap are handled by Home Assistant's native action system, so they behave consistently with official cards.

🌍 Language & numbers

The card uses the language of your Home Assistant profile and formats numbers for that region. It is translated into 41 languages.

Full language list & number formatting (click to expand)

Supported languages

Flag Code Language (English / Native)
🇸🇦 ar Arabic / العربية
🇧🇩 bn Bengali / বাংলা
ca Catalan / Català
🇨🇿 cs Czech / Čeština
🇩🇰 da Danish / Dansk
🇩🇪 de German / Deutsch
🇬🇷 el Greek / Ελληνικά
🇬🇧 en English / English
🇪🇸 es Spanish / Español
🌎 es-419 Spanish (Latin America) / Español (Latinoamérica)
🇪🇪 et Estonian / Eesti
🇫🇮 fi Finnish / Suomi
🇫🇷 fr French / Français
🇮🇳 hi Hindi / हिन्दी
🇭🇷 hr Croatian / Hrvatski
🇭🇺 hu Hungarian / Magyar
🇮🇩 id Indonesian / Bahasa Indonesia
🇮🇹 it Italian / Italiano
🇯🇵 ja Japanese / 日本語
🇰🇷 ko Korean / 한국어
🇱🇹 lt Lithuanian / Lietuvių
🇱🇻 lv Latvian / Latviešu
🇲🇰 mk Macedonian / Македонски
🇳🇴 nb Norwegian Bokmål / Norsk Bokmål
🇳🇱 nl Dutch / Nederlands
🇵🇱 pl Polish / Polski
🇵🇹 pt Portuguese / Português (Portugal)
🇧🇷 pt-BR Portuguese / Português (Brazil)
🇷🇴 ro Romanian / Română
🇷🇺 ru Russian / Русский
🇷🇸 sr Serbian (Cyrillic) / Српски (Ћирилица)
🇷🇸 sr-Latn Serbian (Latin) / Srpski (Latinica)
🇸🇰 sk Slovak / Slovenský
🇸🇮 sl Slovene / Slovenščina
🇸🇪 sv Swedish / Svenska
🇹🇭 th Thai / ไทย
🇹🇷 tr Turkish / Türkçe
🇺🇦 uk Ukrainian / Українська
🇻🇳 vi Vietnamese / Tiếng Việt
🇨🇳 zh-Hans Chinese (Simplified) / 中文(简体)
🇹🇼 zh-Hant Chinese (Traditional) / 中文(繁體)

Important

I use translation tools to help bridge language gaps, as I'm not fluent in every language.

If you notice any mistakes, please understand they are purely unintentional — feel free to reach out on GitHub or Discord to fix it.

More languages may be added in the future to enhance accessibility!

Number formatting

Numbers are displayed based on your regional preferences, using:

  • Your selected language settings (auto)
  • Your specific format (manual selection)
  • Or the system-defined format from your Home Assistant user profile

By default, the card uses standard Arabic numerals (0-9) for maximum compatibility.

🧪 Code quality

CI HACS validation DeepSource Dependabot TypeScript strict Code style: Prettier

Every push runs the lint, type-check, tests and build; releases run the same gate. DeepSource reviews the code, and Dependabot keeps the GitHub Actions up to date.

Tooling: TypeScript · esbuild · ESLint with SonarJS · Prettier · knip · markdownlint · happy-dom · es-check

👥 Contributing

Want more features? Want to improve this card? Contributions are welcome! 🚀

Check out the Contributing Guide to get started.

🙏 Credits & Acknowledgements

  • Resources from Home Assistant
    ➡️ Custom Card Documentation

  • Resources from @thomasloven – thank you!

    ➡️ PreLoading Lovelace Elements
    ➡️ Custom Element Loader Gist

  • Inspired by Mushroom (Apache-2.0 license) — Copyright © Paul Bottein (@piitaya)
    ➡️ For the look & feel

  • Inspired by bar-card (MIT License) — Copyright © Lucas Bramlage (@Gluwc)
    ➡️ No code was copied; this project is an original implementation.

  • Inspired by superstruct (MIT License) — Copyright © Ian Storm Taylor (@ianstormtaylor)
    ➡️ Structural validation ideas to manage inputs (v1.5+). This implementation is original and does not reuse code from the library.

  • Inspired by hass-progress-bar-feature (MIT License) — Copyright © Yury Tilis (@ytilis)
    ➡️ override HA's default feature row sizing behavior, preventing card height increase when using overlay features.

  • Special thanks to @harmonie-durrant
    ➡️ PRs, HACS testing, debugging, Light theme and illustrations:

    • docs/images/example.png
    • docs/images/thumbnail.png
  • Special thanks to @jam3sward & @Duncan1106
    ➡️ README proofreading and improvements

  • Special thanks to @mooseBringer & @RKT62 from Discord
    ➡️ Discord activity
    ➡️ Regular tests & feedbacks

  • Special thanks to all contributors – including those who submitted pull requests, opened issues, and shared feedback (GitHub Issues / Discord)!

📄 License

This project is licensed under the GPL-3.0 license.