Supercharge Your Home Assistant Cards with ha-template: Dynamic Templates Made Easy!

Tired of static, boring Home Assistant custom cards? Wish you could easily inject dynamic data and bring your interfaces to life? The ha-template component is your answer! This lightweight Lit element unlocks the power of Jinja2 templates directly within your custom cards, making them smarter and more informative. Imagine automatically displaying sensor readings, personalized greetings, or contextual information – all updated in real-time.

Why Use ha-template for Your Home Assistant Templates?

ha-template offers a streamlined and efficient way to manage templates in your custom cards. No more wrestling with complex JavaScript or manually updating data.

• Effortless Template Rendering: Simply pass your Home Assistant object, template string, and a fallback value. ha-template handles the rest.
• Automatic Updates: Subscribes to template updates, automatically re-rendering the template value whenever changes occur. Your cards stay current without needing constant refreshing.
• Tiny Footprint: Weighing in at less than 2kB, ha-template won't bloat your system, ensuring optimal performance.
• Fallback Protection: Displays a user-defined fallback value when a template is unavailable, preventing errors and maintaining a smooth user experience. Say goodbye to broken cards!

Installation: Get Started in Seconds

Integrating ha-template into your project is straightforward. Use your preferred package manager:

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

That's it! You're now ready to start using ha-template in your custom cards.

Usage: Unleash the Power of Dynamic Cards

Here's how to seamlessly integrate ha-template into your custom card:

1. Import and Register: Start by importing ha-template and registering it as a custom component.

import registerTemplates from 'ha-template';

registerTemplates(); // Registers ha-template component

2. Implement into your card: Use <ha-template> within your card's render() method.

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

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

In this example, you can make your custom card to update the information with Home Assistant templates about, for example, outside temperature.

3. Pass required properties:
   • hass: This property is the Home Assistant object.
   • template: This property expects a Jinja2 template string.
   • value: Provide a fallback value that displays if the template is not defined.

API: Your Toolkit for Customization

ha-template exposes two key elements for flexible integration:

• HATemplate: The custom Lit component for rendering templates. Import and register it with your own custom element name if desired.
• default: A function to register HATemplate as ha-template. Customize the component name by passing it as an argument.

The HATemplate component accepts the following properties:

• hass: The Home Assistant connection object.
• template: The Jinja2 template string to render.
• value: The fallback value to display when the template is unavailable. This is great for communicating if the temperature sensor has gone offline.
• variables: An object containing custom variables for use within the template.

Contribute and Shape the Future

Want to help improve ha-template? Your contributions are welcome! Check the contributing guidelines for more information on how to get involved.