Simplest custom card

my-custom-card.js

// Simplest possible custom card
// Does nothing. Doesn't look like anything

class MyCustomCard extends HTMLElement {

  setConfig(config) {
    // The config object contains the configuration specified by the user in ui-lovelace.yaml
    // for your card.
    // It will minimally contain:
    // config.type = "custom:my-custom-card"
    // `setConfig` MUST be defined - and is in fact the only function that must be.
    // It doesn't need to actually DO anything, though.
    
    // Note that setConfig will ALWAYS be called at the start of the lifetime of the card
    // BEFORE the `hass` object is first provided.
    // It MAY be called several times during the lifetime of the card, e.g. if the configuration
    // of the card is changed.
  }
  
  set hass(hass) {
    // Whenever anything updates in Home Assistant, the hass object is updated
    // and passed out to every card. If you want to react to state changes, this is where
    // you do it. If not, you can just ommit this setter entirely.
    // Note that if you do NOT have a `set hass(hass)` in your class, you can access the hass
    // object through `this.hass`. But if you DO have it, you need to save the hass object
    // manually, thusly:
    this._hass = hass;
  }
  
  getCardSize() {
    // The height of your card. Home Assistant uses this to automatically
    // distribute all cards over the available columns.
    // This is actually optional. If not present, the cardHeight is assumed to be 1.
    return 1;
  }

}

// This registers the card class as a custom element that can be included in lovelace by
// type: custom:my-custom-card
customElements.define('my-custom-card', MyCustomCard);

/* To use this card:
- Put this file in <config>/www/my-custom-card.js
- Add "/local/my-custom-card.js" to your lovelace resources
- Refresh your browser
- Add a new lovelace card and set its configuration to:
type: custom:my-custom-card

*/

my-custom-card2.js

// A custom card that actually looks like something
// Not like something good, mind you, but *something* at least.

class MyCustomCard2 extends HTMLElement {
  
  setConfig(config) {
    this._config = config;
    
    // Example configuration:
    //
    // type: custom:my-custom-card2
    // entity: light.bed_light
    //
    
    if(!config.entity) {
      // If no entity was specified, this will display a red error card with the message below
      throw new Error('You need to define an entity');
    }
    
    // Make sure this only runs once
    if(!this.setupComplete) {
      // A ha-card element should be the base of all cards
      // Best practice, and makes themes and stuff work
      const card = document.createElement("ha-card");
      
      // At this point, we don't necessarily know anything about the current state
      // of anything, but we can set up the general structure of the card.
      this.nameDiv = document.createElement("div");
      card.appendChild(this.nameDiv);
      
      this.button = document.createElement("button");
      this.button.addEventListener("click", () => this.buttonClicked());
      card.appendChild(this.button);
      
      this.appendChild(card);
      
      this.setupComplete = true;
    }
  }
  
  set hass(hass) {
    this._hass = hass;
    // Update the card in case anything has changed
    if(!this._config) return; // Can't assume setConfig is called before hass is set
    const stateObj = hass.states[this._config.entity];
    
    if(!stateObj) return; // This could be handled more gracefully
    
    this.nameDiv.innerHTML = stateObj.attributes.friendly_name || stateObj.entity_id;
    this.button.innerHTML = stateObj.state === "on" ? "Turn off" : "Turn on";
  }
  
  buttonClicked() {
    const stateObj = this._hass.states[this._config.entity];
    // Sanity checking is left as an exercise for the reader
    const service = stateObj.state === "on" ? "turn_off" : "turn_on";
    
    // Turn on or off the light
    // https://developers.home-assistant.io/docs/frontend_data#hasscallservicedomain-service-data
    this._hass.callService("light", service, {entity_id: this._config.entity});
  }
  
}

customElements.define('my-custom-card2', MyCustomCard2);

my-custom-card3.js

// A version of the same custom card which uses Lit (https://lit.dev) like the core lovelace cards do.

// Lit is imported from a CDN here, but it can also be bundled with your card with webpack or rollup or the like
import { html, LitElement } from "https://unpkg.com/[email protected]/lit-element.js?module";

class MyCustomCard3 extends LitElement {
  
  // This will make parts of the card rerender when this.hass or this._config is changed.
  // this.hass is updated by Home Assistant whenever anything happens in your system.
  static get properties() {
    return {
      hass: {},
      _config: {},
    };
  }

  setConfig(config) {
    this._config = config;
  }

  // The render() function of a LitElement returns the HTML of your card, and any time one or the
  // properties defined above are updated, the correct parts of the rendered html are magically
  // replaced with the new values.  Check https://lit.dev for more info.
  render() {
    if (!this.hass || !this._config) {
      return html``;
    }

    const stateObj = this.hass.states[this._config.entity];
    if (!stateObj) {
      return html` <ha-card>Unknown entity: ${this._config.entity}</ha-card> `;
    }

    // @click below is also LitElement magic
    return html`
      <ha-card>
        <div>${stateObj.attributes.friendly_name || stateObj.entity_id}</div>
        <button @click=${this.buttonClicked}>
          Turn ${stateObj.state === "on" ? "off" : "on"}
        </button>
      </ha-card>
    `;
  }

  buttonClicked() {
    const stateObj = this.hass.states[this._config.entity];
    const service = stateObj.state === "on" ? "turn_off" : "turn_on";

    this.hass.callService("light", service, { entity_id: this._config.entity });
  }
}

customElements.define("my-custom-card3", MyCustomCard3);

my-custom-card4-with-editor.js

// A version of the same custom card that shows up in the card picker dialog and also has a graphical editor
// This also used Lit because it's easy, but everything can be done without that too.

import { html, LitElement } from "https://unpkg.com/[email protected]/lit-element.js?module";

// First we need to make some changes to the custom card class
class MyCustomCard4 extends LitElement {
  static getConfigElement() {
    // Create and return an editor element
    return document.createElement("my-custom-card-editor");
  }

  static getStubConfig() {
    // Return a minimal configuration that will result in a working card configuration
    return { entity: "" };
  }

  // The rest of MyCustomCard4 is exactly like MyCustomCard3 above
  // ...
  //
}

customElements.define("my-custom-card4", MyCustomCard4);

// Next we add our card to the list of custom cards for the card picker
window.customCards = window.customCards || []; // Create the list if it doesn't exist. Careful not to overwrite it
window.customCards.push({
  type: "my-custom-card4",
  name: "My Custom Card",
  description: "A cool custom card",
});

// Finally we create and register the editor itself
class MyCustomCardEditor extends LitElement {

  static get properties() {
    return {
      hass: {},
      _config: {},
    };
  }

  // setConfig works the same way as for the card itself
  setConfig(config) {
    this._config = config;
  }

  // This function is called when the input element of the editor loses focus
  entityChanged(ev) {

    // We make a copy of the current config so we don't accidentally overwrite anything too early
    const _config = Object.assign({}, this._config);
    // Then we update the entity value with what we just got from the input field
    _config.entity = ev.target.value;
    // And finally write back the updated configuration all at once
    this._config = _config;

    // A config-changed event will tell lovelace we have made changed to the configuration
    // this make sure the changes are saved correctly later and will update the preview
    const event = new CustomEvent("config-changed", {
      detail: { config: _config },
      bubbles: true,
      composed: true,
    });
    this.dispatchEvent(event);
  }

  render() {
    if (!this.hass || !this._config) {
      return html``;
    }

    // @focusout below will call entityChanged when the input field loses focus (e.g. the user tabs away or clicks outside of it)
    return html`
    Entity:
    <input
    .value=${this._config.entity}
    @focusout=${this.entityChanged}
    ></input>
    `;
  }
}

customElements.define("my-custom-card-editor", MyCustomCardEditor);

my-custom-card5-bundled.js

// If you don't want to rely on external resources, you will have to "bundle" the lit module into your card.
// One way to do this is using Browserify (https://browserify.org/) with the esmify plugin (https://github.com/mattdesl/esmify)
// This requires you to have npm installed.

// > npm install --save-dev browserify esmify
// > npm install lit browser-resolve

// Then you replace the import statement in the beginning of the file with
import { html, LitElement } from "lit";
// and finally bundle your file with 

// > browserify -p esmify my-custom-card-4-bundled.js > my-custom-card.js

// This should give you a file my-custom-card.js which you can load as a resource.

In my-custom-card2.js line 60 should start with "this._hass ..." instead of "hass. ...". :-).

Fixed. Thanks!

This is the best source of documentation I can find to get started with card development.

The latest update of any part of https://github.com/custom-cards is older than two years. I don't know how is to be estimated for the presence.

I am really wrapping my head around, why it is that difficult to find documentation how to do cards. Home Assistant is a major player in home automation.

// this.hass is updated by Home Assistant whenever anything happens in your system.

Right. I did check this with with a log statement. It renders, when I trigger a different entity.

Upon each update of any entity the card gets rendered. In 99% it's completely unrelated. And yes the official documentation suggests to do it this way. All cards get continuously re-rendered for no reason if they follow this approach.

I suggest a different approach. Put the relevant parts into single reactive states (That is Lit' terminology for internal reactive properties). Use set hass(hass) to set them up, but never make hass a public reactive property.

May be useful to include that the object you push to window.customCards can include a documentationURL key, which will generate a help link to that URL in the frontend card editor.

@thomasloven I'm having issues getting my-custom-card3 to work. I've gotten the first two cards to work, but the later ones seems to have some kind of bug.

I can't see any errors in either the Dev console or HA logs, but there seems to be something wrong somewhere.

@FSund try import lit from https://unpkg.com/[email protected]/lit-element.js?module

@ngocjohn Thanks, that worked! I had a look at the Lit docs and found that this also works

import {LitElement, html} from 'https://cdn.jsdelivr.net/gh/lit/dist@3/core/lit-core.min.js';

I've been having a lot of problems trying to get any js working on home assistant. I tried your first example and I get a configuration error:
"e is undefined"
I get one of these errors (n is undefined is another) for pretty much anything I try when i make a custom card. Any suggestions?

I've been having a lot of problems trying to get any js working on home assistant. I tried your first example and I get a configuration error: "e is undefined" I get one of these errors (n is undefined is another) for pretty much anything I try when i make a custom card. Any suggestions?

Your browser console should be able to tell you more. But it sounds like you are either somehow trying to compile or pack this rather than running it yourself or you managed to import it as the ancient legacy "script" rather than "module".

How can we use translation here ?

// Next we add our card to the list of custom cards for the card picker
window.customCards = window.customCards || []; // Create the list if it doesn't exist. Careful not to overwrite it
window.customCards.push({
  type: "my-custom-card4",
  name: "My Custom Card",
  description: "A cool custom card",
});