Unlock Dynamic Custom Cards: Master Home Assistant Templates with ha-template

Tired of static custom cards in Home Assistant? Do you crave dynamic, reactive displays that update in real-time? The ha-template component is your key to crafting powerful, personalized Home Assistant experiences. This lightweight Lit component makes rendering Home Assistant templates within your custom cards a breeze.

Why Choose ha-template? Real Benefits You Can Use

• Effortless Template Rendering: Stop wrestling with complex JavaScript. ha-template handles template rendering and updates automatically.
• Tiny Footprint: Weighing in at under 2kB, this component won't bloat your Home Assistant installation.
• Automatic Updates: Subscribes to template updates, keeping your custom cards dynamically updated with the latest information. No manual refreshing needed!
• Fallback Value Protection: Display a graceful fallback value when your template is temporarily unavailable, ensuring a smooth user experience. No more broken cards!

Installation: Get Started in Seconds

Installation is quick and painless, just like any other dependency:

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

Usage: Unleash the Power of Templates

Using ha-template in your custom card boils down to a few simple steps:

1. Import and Register: Import and register ha-template as a custom component.
2. Pass the Essentials: Pass the hass object, your template string, and an optional fallback value. ha-template does the rest!

Here's a snippet illustrating how to inject Home Assistant templates into your card:

import registerTemplates from 'ha-template';

registerTemplates(); // Registers ha-template component.
class MyCustomCard extends LitElement {
  // ... other card properties ...

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

    return html`
      <ha-card>
        <ha-template
          hass=${this.hass}
          template=${value_template}
          value=${fallback}
        ></ha-template>
      </ha-card>
    `;
  }
}

Alternatively, you can register the HATemplate component directly:

import { HATemplate} from 'ha-template';

customElements.define('my-template-element', HATemplate);

API: Customize Your Template Rendering

ha-template provides flexibility in how you render your templates.

• HATemplate: The core Lit component for rendering templates. Import and register it as a custom element for fine-grained control.
• default: A function that registers HATemplate as a standard ha-template custom element. You can specify a custom component name if needed.

The HATemplate component accepts the following properties:

• hass: Your Home Assistant connection object. Essential for accessing entities and states.
• template: The Jinja2 template string that defines your dynamic content. This is where you unleash the power of template creation.
• value: A fallback value displayed if the template is not defined or encounters an error. A must-have for gracefully handling unexpected situations.
• variables: (Optional) An object containing custom variables you want to use within your template. Adds another layer of flexibility and customization.

Example: Displaying Sensor Data Dynamically

Let's say you want to display the temperature from a sensor in your custom card, but provide a default value if the sensor is unavailable. Using Home Assistant templates, you can easily accomplish this:

html`
  <ha-template
    hass=${this.hass}
    template="The current temperature is {{ states('sensor.temperature') }}°C."
    value="Temperature unavailable"
  ></ha-template>
`;

This example showcases the utility of template rendering in Home Assistant.

Contribute and Shape the Future

Want to enhance ha-template and make it even more powerful? Contributions are welcome! Consult the contributing guidelines (in the original README) to get started. Your ideas and code can help countless Home Assistant users build amazing custom cards.