ha-template

Home Assistant Template Component

A tiny (<2kB) lit component for rendering templates in Home Assistant custom cards

ha-template is a tiny Lit component that conveniently handles rendering templates in Home Assistant custom cards. It subscribes to template updates, automatically rerenders them along with the template value and displays a fallback value if template is not available.

Installing

💡 Tip: If you like this project, consider becoming a patron:

or just buy me a cup of ☕️ or 🥤:

Install this utility as any other dependency:

npm install -S ha-template
# or
yarn add ha-template

Usage

Use ha-template in your card by importing and registering it as a custom component.

Pass hass object, template string and optional falback value. ha-template will handle template rendering and updating automatically.

import registerTemplates from 'ha-template';

// Register ha-template component.
// You can pass custom component name, if you want so.
registerTemplates();

class MyCustomCard extends LitElement {
  static get properties() {
    return {
      hass: Object,
      config: Object,
    };
  }

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

  render() {
    const value_template = this.config;
    const fallback = 'Unknown';

    // Use <ha-template> in your card.
    //
    // Pass hass object, template and a fallback value.
    // Fallback value will replace with the result of rendered template.
    // If template is not defined, fallback value will be used.
    return html`
      <ha-card>
        <ha-template
          hass=${this.hass}
          template=${value_template}
          value=${fallback}
        ></ha-template>
      </ha-card>
    `;
  }
}

Alternatively, you can register HATemplate as a custom element on your own:

import { HATemplate } from 'ha-template';

// Register HATemplate as a custom element.
customElements.define(component, HATemplate);

API

ha-template has two exports:

1. HATemplate - a custom lit-component that provides a convenient way to render templates. You can import it and register it as a custom element.
2. default - a function that registers HATemplate as a ha-tempalte custom element, by default. You can pass custom component name, if you want so.

HATemplate component accepts these properties:

1. hass - an object of Home Assistant connection.
2. template - a string that contains a Jinja2 template.
3. value - a fallback value that will be used if template is not defined. Will be replaced by template result.
4. variables - an object of custom variables to be used within the template.

Development

Want to contribute to the project?

First of all, thanks! Check contributing guideline for more information.

License

MIT © Denys Dovhan