Ha-nunjucks NPM

ha-nunjucks

A simple wrapper for nunjucks for use with Home Assistant frontend custom components to render templates. This repository offers an easy way for developers to add templating support to Home Assistant custom cards.

What is nunjucks?

Nunjucks is a templating engine for JavaScript that is heavily inspired by jinja2. Home Assistant uses jinja2 to process templates in card configurations on the backend, so the syntax of jinja2 and Nunjucks is virtually the same. This makes it an excellent alternative for Home Assistant templating for custom cards.

While some Home Assistant native cards support templating for certain fields, implementing proper Home Assistant jinja2 template support in custom cards is difficult. The only custom module that manages to do so (AFAIK) is card-mod, and it's implementation is hard to port to other projects. This project offers a much easier plug and play solution to adding template support to custom cards.

Usage

Install using npm:

npm install ha-nunjucks

Then import renderTemplate from ha-nunjucks and provide it with the hass object and a template string you want to process.

import { renderTemplate } from 'ha-nunjucks';

const renderedString = renderTemplate(this.hass, templateString);

Rather than rendering templates on the backend, nunjucks renders templates on the frontend. This repository uses the Home Assistant object present in all custom cards to read entity state data.

You can also provide additional context to the renderTemplate function to pass to nunjucks if you want to make additional variables or project specific functions available to your users for use in templates.

import { renderTemplate } from 'ha-nunjucks';

const context = {
  foo: 'bar',
  doThing(thing: string) {
    return `doing ${thing}!`;
  },
};

const renderedString = renderTemplate(this.hass, templateString, context);

Available Extensions

The catch to this approach of rendering jinja2/nunjucks templates is that we have to reimplement all of the Home Assistant template extension functions and filters. If there are functions or filters that you use that are not currently supported, please make a feature request or try adding it to the project yourself and create a pull request.

So far a subset of the Home Assistant template extension functions have been implemented as documented below.

Variables

These variables just remap Python built-in constants to JavaScript ones.

Python	JavaScript
True	true
False	false
None	null

Frontend Data Hass Object

The frontend data hass object has been exposed to users to call upon.

Because entity IDs contain periods in them, it's better to access it using bracket notation like so:

{{ hass["states"]["light.sunroom_ceiling"]["state"] }}

You can also use dot notation for everything but the entity ID.

{{ hass.states["light.sunroom_ceiling"].state }}

States

Functions used to determine an entity's state or an attribute.

Name	Arguments	Description
states	entity_id	Returns the state string of the given entity.
is_state	entity_id, value	Compares an entity's state with a specified state or list of states and returns `true` or `false`.
state_attr	entity_id, attribute	Returns the value of the attribute or `undefined` if it doesn't exist.
is_state_attr	entity_id, attribute, value	Tests if the given entity attribute is the specified value.
has_value	entity_id	Tests if the given entity is not unknown or unavailable.

Immediate If

A shorthand for an if else statement.

Name	Arguments	Description
iif	condition, if_true, if_false, if_none	Immediate if. Returns the value of `if_true` if the condition is true, the value of `if_false` if it's false, and the value of `if_none` if it's `undefined`, `null`, or an empty string. All arguments except `condition` are optional. Cannot be used as a filter.