Custom badge

Badges are small widgets that sit at the top of a view, above all cards. We offer a built-in badge, the entity badge, but you're not just limited that one. You can build and use your own!

Defining your badge

Defining a badge is done in a very similar way to defining a custom card.

Let's create a basic badge that displays custom text at the top of the screen. Create a new file in your Home Assistant config dir as <config>/www/text-badge.js and put in the following contents:

class TextBadge extends HTMLElement {
  // Whenever the state changes, a new `hass` object is set. Use this to
  // update your content.
  set hass(hass) {
    this._hass = hass;
    this.updateContent();
  }

  // The user supplied configuration. Throw an exception and Home Assistant
  // will render an error badge.
  setConfig(config) {
    if (!config.entity) {
      throw new Error("You need to define an entity");
    }
    this.config = config;
    this.updateContent();
  }

  updateContent() {
    if (!this.config || !this._hass) return;

    const entityId = this.config.entity;
    const state = this._hass.states[entityId];
    const stateStr = state ? state.state : "unavailable";

    this.innerHTML = `<p>${stateStr}</p>`;
  }
}

customElements.define("text-badge", TextBadge);

Referencing your new badge

In our example badge, we defined a badge with the tag text-badge (see last line), so our badge type will be custom:text-badge. And because you created the file in your <config>/www directory, it will be accessible in your browser via the url /local/ (if you have recently added the www folder you will need to re-start Home Assistant for files to be picked up).

Add a resource to your dashboard configuration with URL /local/text-badge.js and type module (resource docs).

You can then use your badge in your dashboard configuration:

# Example dashboard configuration
views:
  - name: Example
    badges:
      - type: "custom:text-badge"
        entity: light.bedside_lamp

API

Custom badges are defined as a custom element. It's up to you to decide how to render your DOM inside your element. You can use Polymer, Angular, Preact or any other popular framework (except for React – more info on React here).

Home Assistant will call setConfig(config) when the configuration changes (rare). If you throw an exception if the configuration is invalid, Home Assistant will render an error badge to notify the user.

Home Assistant will set the hass property when the state of Home Assistant changes (frequent). Whenever the state changes, the component will have to update itself to represent the latest state.

Graphical badge configuration

Your badge can define a getConfigElement method that returns a custom element for editing the user configuration. Home Assistant will display this element in the badge editor in the dashboard.

Your badge can also define a getStubConfig method that returns a default badge configuration (without the type: parameter) in json form for use by the badge type picker in the dashboard.

Home Assistant will call the setConfig method of the config element on setup. Home Assistant will update the hass property of the config element on state changes, and the lovelace element, which contains information about the dashboard configuration.

Changes to the configuration are communicated back to the dashboard by dispatching a config-changed event with the new configuration in its detail.

To have your badge displayed in the badge picker dialog in the dashboard, add an object describing it to the array window.customBadges. Required properties of the object are type and name (see example below).

import "./text-badge-editor.js";

class TextBadge extends HTMLElement {
  
  ...

  static getConfigElement() {
    return document.createElement("text-badge-editor");
  }

  static getStubConfig() {
    return { entity: "sun.sun" };
  }
}

customElements.define("text-badge", TextBadge);

class TextBadgeEditor extends HTMLElement {
  setConfig(config) {
    this._config = config;
  }

  configChanged(newConfig) {
    const event = new Event("config-changed", {
      bubbles: true,
      composed: true,
    });
    event.detail = { config: newConfig };
    this.dispatchEvent(event);
  }
}

customElements.define("text-badge-editor", TextBadgeEditor);
window.customBadges = window.customBadges || [];
window.customBadges.push({
  type: "text-badge",
  name: "Text badge",
  preview: false, // Optional - defaults to false
  description: "A custom badge made by me!", // Optional
  documentationURL:
    "https://developers.home-assistant.io/docs/frontend/custom-ui/custom-badge", // Adds a help link in the frontend badge editor
});