home-assistant-javascript-templates

home-assistant-javascript-templates

A JavaScript utility to render Home Assistant JavaScript templates.

Install

npm

npm install home-assistant-javascript-templates

yarn

yarn add home-assistant-javascript-templates

PNPM

pnpm add home-assistant-javascript-templates

Basic Usage

Usage with commonJS

const HomeAssistantJavaScriptTemplates = require('home-assistant-javascript-templates');

const renderer = new HomeAssistantJavaScriptTemplates(
    document.querySelector('home-assistant').hass
);

renderer.renderTemplate('... template string ...');

Usage with ES6 modules

import HomeAssistantJavaScriptTemplates  from 'home-assistant-javascript-templates';

const renderer = new HomeAssistantJavaScriptTemplates(
    document.querySelector('home-assistant').hass
);

renderer.renderTemplate('... template string ...');

API

The package exposes a class that needs to be instantiated and is this isntance the one that you need to use in your code.

HomeAssistantJavaScriptTemplates class

Main class of the library, it is the default export in the package.

new HomeAssistantJavaScriptTemplates(hass, throwErrors = false);

Parameter	Optional	Description
hass	no	A valid hass object
throwErrors	yes	Indicates if the library should throw if the template contains any error. If not it will log the errors as a warning in the console and return undefined instead.

renderTemplate method

This is the main method to render JavaScript templates, it needs a string as a parameter. Inside this string you can use several objects and methods.

Objects and methods available in the templates

hass

The same hass object that was sent to the class

states

states could be used in two ways, as a function or as an object. When using it as function it only allows an entity id as a parameter and it will return the state of that entity. When using it as an object, you can use also an entity id but in those cases it will return the entire state object, so you need to access its state property to get the state value. When using it as an object with a domain, it will return an array with all the states of that domain.

Note: If you try to use states as a function sending a domain it will throw an error.

// Using states as a function
states('device_tracker.paulus') // returns the state of the entity id 'device_tracker.paulus'

// Using states as an object
states['device_tracker.paulus'].state // returns the state of the entity id 'device_tracker.paulus'
states['device_tracker'] // returns an array with all the states of the 'device_tracker' domain

is_state

Method to check if the state of an entity is equal to a certain value. It returns a boolean. If the entity id doesn‘t exist it returns false.

is_state('device_tracker.paulus', 'not_home')

state_attr

Method to return the value of the state attribute or undefined if it doesn’t exist.

state_attr('device_tracker.paulus', 'battery')

is_state_attr

Method to test if the given entity attribute is the specified state. It returns a boolean, if the entity doesn‘t exist it returns false.

is_state_attr('device_tracker.paulus', 'battery', 40)

has_value

Method to test if the given entity is not unknown or unavailable. It returns a boolean, if the entity doesn‘t exist it returns false.

has_value('sensor.my_sensor')

device_attr

Method that returns the value of an attribute for the given device id or undefined if it doesn’t exist.

device_attr('706ad0ebe27e105d7cd0b73386deefdd')

is_device_attr

Method to test if the value of a device attribute matches a value. It returns a boolean, if the device id doen‘t exist it returns false.

is_device_attr('706ad0ebe27e105d7cd0b73386deefdd', 'manufacturer', 'Synology')

device_id

Method to return the device id for a given entity id or undefined if the entity doesn‘t exist.

device_id('sensor.my_sensor')

areas

Method to return an array with all the areas ids.

areas()

area_id

Method to return the area id for a given device id, entity id, or area name. It returns undefined if the area doesn‘t exist.

area_id('b8c1c9dd23cb82bbfa09b5657f41d04f')
area_id('sensor.my_sensor')
area_id('Woonkamer')

area_name

Method to return the area name for a given device id, entity id, or area id. It returns undefined if the area doesn‘t exist.

area_name('b8c1c9dd23cb82bbfa09b5657f41d04f')
area_name('sensor.my_sensor')
area_name('woonkamer')

area_entities

Method to return an array of entity ids tied to a given area id or area name. If the area doesn‘t exist it returns an empty array.

area_entities('woonkamer')
area_entities('Woonkamer')

area_devices

Method to return an array of device ids tied to a given area id or area name. If the area doesn‘t exist it returns an empty array.

area_devices('woonkamer')
area_devices('Woonkamer')

user_name

Property to return the name of the user logged in in Home Assistant. It returns a string.

user_name

user_is_admin

Property to return if the user logged in in Home Assistant is admin or not. It returns a boolean.

user_is_admin

user_is_owner

Property to return if the user logged in in Home Assistant is the owner. It returns a boolean.

user_is_owner

Examples

Get a device attribute and return a formatted text with it

import HomeAssistantJavaScriptTemplates  from 'home-assistant-javascript-templates';

const renderer = new HomeAssistantJavaScriptTemplates(
    document.querySelector('home-assistant').hass
);

/**
 * Get the device id of an entity
 * With the device id get an attribute of the device
 * Return the value of the attribute prefixed with "sn: "
 * It will return something like "sn: 123456"
 */
renderer.renderTemplate(`
    const deviceId = device_id("binary_sensor.koffiezetapparaat_aan");
    const serialNumber = device_attr(deviceId, "serial_number");
    return "sn:" + serialNumber;
`);

Get all the available updates

import HomeAssistantJavaScriptTemplates  from 'home-assistant-javascript-templates';

const renderer = new HomeAssistantJavaScriptTemplates(
    document.querySelector('home-assistant').hass
);

renderer.renderTemplate(`
    const udatesEntities = states['update'];
    const updatesEntitiesOn = udatesEntities?.filter((entity) => entity.state === 'on');
    return updatesEntitiesOn?.length || 0;
`);

Changelog

[1.2.0] - 2024-01-28

• Rollback the None returns and return undefined in these cases.
• Throw an error if the states method is used with a domain