# ha-nunjucks > Wrapper for nunjucks for use with Home Assistant frontend custom components to render templates Latest version **1.7.9** (published 2026-09-29) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install ha-nunjucks pnpm add ha-nunjucks yarn add ha-nunjucks bun add ha-nunjucks ``` ## Health **Score 75/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 1.7.9 | | Published | 2026-09-29 | | First published | 2023-12-05 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 9 | | Unpacked size | 210.5 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | Author | Nerwyn | | Maintainers | nerwyn | ## Links - npm: https://www.npmjs.com/package/ha-nunjucks - Repository: https://github.com/Nerwyn/ha-nunjucks - Homepage: https://github.com/Nerwyn/ha-nunjucks#readme - Issues: https://github.com/Nerwyn/ha-nunjucks/issues - npm.io page: https://npm.io/package/ha-nunjucks ## Dependencies (9) - [buffer](https://npm.io/package/buffer.md) ^6.0.3 - [stream](https://npm.io/package/stream.md) npm:stream-browserify@^3.0.0 - [slugify](https://npm.io/package/slugify.md) ^1.6.9 - [nunjucks](https://npm.io/package/nunjucks.md) ^3.2.4 - [@noble/hashes](https://npm.io/package/@noble/hashes.md) ^2.4.0 - [python-struct](https://npm.io/package/python-struct.md) ^1.1.3 - [ts-py-datetime](https://npm.io/package/ts-py-datetime.md) ^0.10.0 - [mersenne-twister](https://npm.io/package/mersenne-twister.md) ^1.1.0 - [home-assistant-js-websocket](https://npm.io/package/home-assistant-js-websocket.md) ^9.6.0 ## Recent versions - 1.7.9 (latest) — 2026-09-29 - 1.7.7-beta.3 (beta) — 2026-06-30 - 1.7.0-alpha.1 (alpha) — 2025-12-25 - 1.7.8 — 2026-09-13 - 1.7.7 — 2026-07-05 - 1.7.7-beta.2 — 2026-06-30 - 1.7.7-beta.1 — 2026-06-28 - 1.7.6 — 2026-04-23 - 1.7.5 — 2026-03-16 - 1.7.4 — 2026-03-08 - 1.7.3 — 2026-03-04 - 1.7.1 — 2026-03-04 - 1.7.1-beta.1 — 2026-03-03 - 1.7.0 — 2025-12-26 - 1.7.0-beta.5 — 2025-12-26 - … 85 more at https://npm.io/package/ha-nunjucks/versions ## README # ha-nunjucks [![License][license-shield]](LICENSE.md) ![Project Maintenance][maintenance-shield] [![GitHub Activity][last-commit-shield]][commits] [![Community Forum][forum-shield]][forum] [![Github][github]][github] A wrapper for [nunjucks](https://www.npmjs.com/package/nunjucks) for use with Home Assistant frontend custom components to render [templates](https://www.home-assistant.io/docs/templating/) instanteneously at HTML render time. This repository offers a fast and easy way for developers to add templating support to Home Assistant custom cards. ## What is nunjucks? [Nunjucks](https://mozilla.github.io/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 to Home Assistant core jinja2 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 can be difficult. Additionally Home Assistant jinja2 templates are processed by the Python backend, and use subscriptions which must be managed and do not play as well with dynamic custom variables or synchronous frontend rendering. Nunjucks templates are processed by the frontend using the frontend [`hass`](https://developers.home-assistant.io/docs/frontend/data/) object before your custom card's HTML is rendered, making nunjucks templating synchronous, near instanteous, and easier to use than traditional jinja2 templates. ## Installation and Usage If you are not a developer, skip this section. This module has to be installed as a dependency of a Home Assistant frontend add-on like a custom card. ### Installation Install using npm: ```shell npm install ha-nunjucks ``` ### Usage Import `renderTemplate` from `ha-nunjucks` and provide it with the `hass` object and a template string you want to process. ```typescript import { renderTemplate } from 'ha-nunjucks'; const renderedString = renderTemplate(this.hass, templateString); ``` That's it! The result of `renderTemplate` is the rendered template for you to use. In unit and integration testing render time for a single template is under 1 ms and shouldn't cause any latency in your projects. 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. A single shared Nunjucks environment is used for the frontend across all custom element instances that use ha-unjucks, which helps with initial load times. If multiple frontend add-ons are installed which use different versions of ha-nunjucks, the global version will be overwritten with the latest available version. You can also provide 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. ```typescript import { renderTemplate } from 'ha-nunjucks'; const context = { foo: 'bar', doThing(thing: string) { return `doing ${thing}!`; }, config: { entity: 'foo.bar', attribute: 'baz_bah', }, }; const renderedString = renderTemplate(this.hass, templateString, context); ``` `renderTemplate` will try to validate that inputs contain valid templates by default using the exported function `hasTemplate`. You can disable this by setting the fourth argument of `renderTemplate` to `false`. This way you can perform this check yourself before any additional templating setup you perform in your code. ```typescript import { hasTemplate, renderTemplate } from 'ha-nunjucks'; if (!hasTemplate(templateString)) { return templateString; } const context = { foo: 'bar', doThing(thing: string) { return `doing ${thing}!`; }, config: { entity: 'foo.bar', attribute: 'baz_bah', }, }; const renderedString = renderTemplate( this.hass, templateString, context, false, ); ``` ### Return Types `renderTemplate` will return a string unless the result is `true` or `false` (_not_ case sensitive), in which case it will return a boolean. When the return type is expected to be a number, end users should cast these values using the nunjucks `int` or `float` filters to prevent undesired behavior caused by JavaScript forcing operations between disparate variable types. Numbers are not returned by default to prevent leading and trailing zeroes from being truncated from numerical strings. `renderTemplate` will return an empty string for strings that may have been cast from nullish non-numerical values, such as `undefined`, `null`, and `None` (case sensitive). ### Global Environment ha-nunjucks creates one global object on the browser window, which contains an nunjucks environment used by all custom element instances that use ha-nunjucks. This prevents redundant re-initializing of ha-nunjucks across many custom elements and a significant initial page load speedup. If multiple different custom elements use ha-nunjucks, they will all use the same shared nunjucks environment which is initialized the first time one of them is loaded. ha-nunjucks will also check the version that is loaded, and overwrite it if one custom element has a new version than the currently loaded version. ## Available Extensions All of the [Home Assistant template functions](https://www.home-assistant.io/template-functions/) have been implemented into this package. If there are newer functions that you use that are not currently supported or behave unexpectedly, please make a feature request or try adding it to the project yourself and create a pull request. Do note that some template extensions behave differently from their Home Assistant backend jinja2 counterparts due to differences between Python and JavaScript and language feature constraints. Template extensions can be functions, tests, filters, and/or constants. Functions are called like a regular programming function, such as `states()` or `floors()`. Filters are added to the end of a string using a pipe character like `123.45 | int` or `"light.lounge" | state_attr("brightness")`. Tests are functions which return booleans and can be used in an if statement like `if "foo" is string_like`, not to be confused with functions that return booleans and can be used in if statements like `if is_state("light.lounge", "on")`. Contants are static values, and are just called as is like `{{ True }}` or `{{ pi }}`. In addition to the template extensions implemented in this package, you also have access to the nunjucks builtin functions and filters. [Read the nunjucks templating documentation for more information](https://mozilla.github.io/nunjucks/templating.html). ### Python Constants These just remap Python built-in constants to JavaScript ones. | Python | JavaScript | | ------ | ---------- | | True | true | | False | false | | None | null | ### [Frontend Data Hass Object](https://developers.home-assistant.io/docs/frontend/data/) The frontend data `hass` object has been exposed to users to call upon. Because entity IDs contain periods in them, you cannot use dot notation when accessing an entity's state object using it. You have to use bracket notation like so: `{{ hass.states["light.sunroom_ceiling"].state }}` For convenience, the `hass.states` object is rebuilt as a separate object that can be accessed with dot notation. Because of JavaScript limitations not allowing for functions and object to share the same name, it has been named `_states`. Note that this object is only rebuilt as needed and can cause a performance hit. It is preferable to use `hass.states` or a template function instead. `{{ _states.light.sunroom_ceiling.state }}` You do have to use bracket notation for arrays within state objects. `{{ _states.light.sunroom_ceiling.attributes.supported_color_modes[0] }}` ### States Functions used to determine an entity's state or an attribute. | Name | Type | Arguments | Description | | -------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | [states](https://www.home-assistant.io/template-functions/states/) | function, filter | entity_id, rounded (default false), with_unit (default false) | Returns the state string of the given entity. Optionally round numerical states and append the unit of measurement. | | [is_state](https://www.home-assistant.io/template-functions/is_state/) | function | entity_id, value | Compares an entity's state with a specified state or list of states and returns `true` or `false`. | | [state_attr](https://www.home-assistant.io/template-functions/state_attr/) | function, filter | entity_id, attribute | Returns the value of the attribute or `undefined` if it doesn't exist. | | [is_state_attr](https://www.home-assistant.io/template-functions/is_state_attr/) | function | entity_id, attribute, value | Tests if the given entity attribute is the specified value. | | [has_value](https://www.home-assistant.io/template-functions/has_value/) | function, filter | entity_id | Tests if the given entity is not unknown or unavailable. | ### State Translated | Name | Type | Arguments | Description | | -------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [state_translated](https://www.home-assistant.io/template-functions/state_translated/) | function, filter | entity_id, state (optional) | Returns the formatted and translated state of an entity or provided state using a language that is currently configured in the general settings. | | attr_name_translated | function, filter | entity_id, attr_name | Returns the formatted and translated attribute name of an entity using a language that is currently configured in the general settings. | | attr_value_translated | function, filter | entity_id, attr_name, attr_value (optional) | Returns the formatted and translated attribute value of an entity or provided attribute value using a language that is currently configured in the general settings. | | number_translated | function, filter | value | Returns the formatted and translated input number using a language that is currently configured in the general settings. | | date_translated | function, filter | value | Returns the formatted and translated input date or datetime as a date using a language that is currently configured in the general settings. | | time_translated | function, filter | value | Returns the formatted and translated input time or datetime as a time using a language that is currently configured in the general settings. | | datetime_translated | function, filter | value | Returns the formatted and translated input datetime using a language that is currently configured in the general settings. | ### Groups | Name | Type | Arguments | Description | | ------------------------------------------------------------------ | ---------------- | --------- | ------------------------------------------------------------------------------------------------- | | [expand](https://www.home-assistant.io/template-functions/expand/) | function, filter | args | Retrieve state objects for provided entities and sort. Expands group entities into their members. | ### Entities | Name | Type | Arguments | Description | | -------------------------------------------------------------------------------------- | -------- | --------- | ------------------------------------------ | | [is_hidden_entity](https://www.home-assistant.io/template-functions/is_hidden_entity/) | function | entity_id | Returns whether an entity has been hidden. | ### Devices | Name | Type | Arguments | Description | | ------------------------------------------------------------------------------------ | ---------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------- | | [device_entities](https://www.home-assistant.io/template-functions/device_entities/) | function, filter | device_id | Returns a list of entities that are associated with a given device ID. | | [device_attr](https://www.home-assistant.io/template-functions/device_attr/) | function, filter | device_or_entity_id, attr_name | Returns the value of attr_name for the given device or entity ID. | | [is_device_attr](https://www.home-assistant.io/template-functions/is_device_attr/) | function | device_or_entity_id, attr_name, attr_value | Returns whether the value of attr_name for the given device or entity ID matches attr_value. | | [device_id](https://www.home-assistant.io/template-functions/device_id/) | function, filter | entity_id | Returns the device ID for a given entity ID or device name. | | [device_name](https://www.home-assistant.io/template-functions/device_name/) | function, filter | device_or_entity_id | Returns the device name as defined by user or default for a give entity or device ID. | ### Config Entries **NOTE**: Relies on async request on initial page load. May return nothing on first render. | Name | Type | Arguments | Description | | ---------------------------------------------------------------------------------------- | ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [config_entry_id](https://www.home-assistant.io/template-functions/config_entry_id/) | function, filter | entity_id | Returns the config entry ID for a given entity ID. | | [config_entry_attr](https://www.home-assistant.io/template-functions/config_entry_attr/) | function, filter | config_entry_id, attr | Returns the value of `attr` for the config entry of the given entity ID. The following attributes are allowed: `domain`, `title`, `state`, `source`, `disabled_by`. | ### Floors | Name | Type | Arguments | Description | | ---------------------------------------------------------------------------------- | ---------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- | | [floors](https://www.home-assistant.io/template-functions/floors/) | function | | Returns the full list of floor IDs that include an area. | | [floor_id](https://www.home-assistant.io/template-functions/floor_id/) | function, filter | lookup_value | Returns the floor ID for a given floor name or alias, device ID, entity ID, area ID, or area name or alias. | | [floor_name](https://www.home-assistant.io/template-functions/floor_name/) | function, filter | lookup_value | Returns the floor name for a given device ID, entity ID, area ID, area name, or floor ID. | | [floor_areas](https://www.home-assistant.io/template-functions/floor_areas/) | function, filter | floor_name_or_id | Returns the list of area IDs tied to a given floor ID or name. | | [floor_entities](https://www.home-assistant.io/template-functions/floor_entities/) | function, filter | floor_name_or_id | Returns the list of entity IDs tied to a given floor ID or name. | ### Areas | Name | Type | Arguments | Description | | -------------------------------------------------------------------------------- | ---------------- | --------------- | ------------------------------------------------------------------- | | [areas](https://www.home-assistant.io/template-functions/areas/) | function | | Returns the full list of area IDs. | | [area_id](https://www.home-assistant.io/template-functions/area_id/) | function, filter | lookup_value | Returns the area ID for a given device ID, entity ID, or area name. | | [area_name](https://www.home-assistant.io/template-functions/area_name/) | function, filter | lookup_value | Returns the area name for a given device ID, entity ID, or area ID. | | [area_entities](https://www.home-assistant.io/template-functions/area_entities/) | function, filter | area_name_or_id | Returns the list of entity IDs tied to a given area ID or name. | | [area_devices](https://www.home-assistant.io/template-functions/area_devices/) | function, filter | area_name_or_id | Returns the list of device IDs tied to a given area ID or name. | ### Entities For An Integration **NOTE**: Relies on async request on initial page load. May return nothing on first render. | Name | Type | Arguments | Description | | ---------------------------------------------------------------------------------------------- | -------- | --------------------------------- | ---------------------------------------------------------------------------------------------- | | [integration_entities](https://www.home-assistant.io/template-functions/integration_entities/) | function | integration_or_config_entry_title | Returns a list of entities that are associated with a given integration or config entry title. | ### Labels **NOTE**: Relies on async request on initial page load. May return nothing on first render. | Name | Type | Arguments | Description | | ---------------------------------------------------------------------------------------- | ---------------- | ----------------------- | ------------------------------------------------------------------------------------------ | | [labels](https://www.home-assistant.io/template-functions/labels/) | function, filter | lookup_value (optional) | Returns the full list of label IDs, or those for a given area ID, device ID, or entity ID. | | [label_id](https://www.home-assistant.io/template-functions/label_id/) | function, filter | lookup_value | Returns the label ID for a given label name. | | [label_name](https://www.home-assistant.io/template-functions/label_name/) | function, filter | lookup_value | Returns the label name for a given label ID. | | [label_description](https://www.home-assistant.io/template-functions/label_description/) | function, filter | lookup_value | Returns the label description for a given label ID. | | [label_areas](https://www.home-assistant.io/template-functions/label_areas/) | function, filter | label_name_or_id | Returns the list of area IDs tied to a given label ID or name. | | [label_devices](https://www.home-assistant.io/template-functions/label_devices/) | function, filter | label_name_or_id | Returns the list of device IDs tied to a given label ID or name. | | [label_entities](https://www.home-assistant.io/template-functions/label_entities/) | function, filter | label_name_or_id | Returns the list of entity IDs tied to a given label ID or name. | ### Issues **NOTE**: Relies on async request on initial page load. May return nothing on first render. | Name | Type | Arguments | Description | | ------------------------------------------------------------------ | -------- | ---------------- | -------------------------------------------------------------------------------------- | | [issues](https://www.home-assistant.io/template-functions/issues/) | function | | Returns all open issues as a mapping of `domain,issue_id` strings to the issue object. | | [issue](https://www.home-assistant.io/template-functions/issue/) | function | domain, issue_id | Returns an issue object. | ### Immediate If A shorthand for an if else statement. | Name | Type | Arguments | Description | | ------------------------------------------------------------ | ---------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [iif](https://www.home-assistant.io/template-functions/iif/) | function, filter | condition, if_true (optional), if_false (optional), if_none (optional) | 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. | ### Time **NOTE**: - JS Date does not support time precision below 1 millisecond, while Python datetime supports microsecond precision. Microsecond arguments are not available for these methods. - JS Date is not as good at handling timezones as Python datetime. Be careful about timezone differences! You can try to account for this using the `utc` flags and/or by including a timezone offset in a datetime string to parse using `as_datetime` or `strptime`. - Including time extensions in your templates does not cause them to refresh more regularly by themselves, although they will still update whenever the `hass` object does. If you are a developer, you have to implement this behavior yourself in your custom cards. | Name | Type | Arguments | Description | | -------------------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [now](https://www.home-assistant.io/template-functions/now/) | function | | Returns a datetime object that represents the current time in your time zone. | | [utcnow](https://www.home-assistant.io/template-functions/utcnow/) | function | | Returns a datetime object of the current time in the UTC timezone. | | [today_at](https://www.home-assistant.io/template-functions/today_at/) | function, filter | value | Converts a string containing a military time format to a datetime object with today’s date in your time zone. Defaults to midnight (00:00). | | [as_datetime](https://www.home-assistant.io/template-functions/as_datetime/) | function, filter | value, fallback (optional), utc (default true) | Converts a string containing a timestamp, or valid UNIX timestamp, to a datetime object. If that fails, it returns the fallback value. When the input is already a datetime object it will be returned as is. in case the input is a datetime.date object, midnight will be added as time. | | [as_timestamp](https://www.home-assistant.io/template-functions/as_timestamp/) | function, filter | value, fallback (optional) | Converts a datetime object or string to UNIX timestamp. If that fails, returns the fallback value. | | [as_local](https://www.home-assistant.io/template-functions/as_local/) | function, filter | value | Converts a datetime object to local time. | | [strptime](https://www.home-assistant.io/template-functions/strptime/) | function | value, format, fallback (optional), utc (default false) | Parses a string based on a [format](https://d3js.org/d3-time-format#locale_format) and returns a datetime object. If that fails, it returns the default value. | | [relative_time](https://www.home-assistant.io/template-functions/relative_time/) | function, filter | value | Returns a human readable string indicating the differenceb between now and an input past datetime object. Only uses the largest unit (years, months, days, hours, minutes, seconds) rounded. | | [time_since](https://www.home-assistant.io/template-functions/time_since/) | function, filter | value, precision (default 1) | Returns a human readable string indicating the difference between now and an input past datetime object. `precision` indicates how many units (years, months, days, hours, minutes, seconds) to use, with the last unit being rounded and 0 being the same as 6. If the input datetime is in the future it returns the input. If the input datetime is not a datetime object it returns nothing. | | [time_until](https://www.home-assistant.io/template-functions/time_until/) | function, filter | value, precision (default 1) | Returns a human readable string indicating the difference between now and an input future datetime object. `precision` indicates how many units (years, months, days, hours, minutes, seconds) to use, with the last unit being rounded and 0 being the same as 6. If the input datetime is in the past it returns the input. If the input datetime is not a datetime object it returns nothing. | | [as_timedelta](https://www.home-assistant.io/template-functions/as_timedelta/) | function, filter | value | Converts a string to a timedelta object. Expects data in the format `DD HH:MM:SS.uuuuuu`, `DD HH:MM:SS,uuuuuu`, or as specified by ISO 8601 (e.g. `P4DT1H15M20S` which is equivalent to `4 1:15:20`) or PostgreSQL’s day-time interval format (e.g. `3 days 04:05:06`). | | [timestamp_local](https://www.home-assistant.io/template-functions/timestamp_local/) | filter | value, fallback (optional) | Converts a UNIX timestamp to the ISO format string representation as date/time in your local timezone. If that fails, returns the `fallback` value. | | [timestamp_utc](https://www.home-assistant.io/template-functions/timestamp_utc/) | filter | value, fallback (optional) | Converts a UNIX timestamp to the ISO format string representation as date/time in UTC timezone. If that fails, returns the `fallback` value. | | [timestamp_custom](https://www.home-assistant.io/template-functions/timestamp_custom/) | filter | value, format, local (default true), fallback (optional) | Converts a UNIX timestamp to its string representation based on a custom format. Uses the local timezone by default. If that fails, returns the `fallback` value. | In addition to these functions, you have access to [a datetime library](https://github.com/Nerwyn/ts-py-datetime) which emulates the Python datetime module in TypeScript. You can instantiate `date`, `time`, `datetime`, and `timedelta` objects using the `dt` object. You can then access it's class methods using these objects. To use the static method and constants of these classes, you can reference them directly without prefixing them with `dt`. See the README in the datetime repository linked above for more information on how to use it. | Name | Type | Arguments | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | dt | object | | The datetime object, which contains constructor functions for date, datetime, time, and timedelta along with some constants. | | dt.date | function | year, month, day | Returns a date object. | | dt.datetime | function | year, month, day, hour (default 0), minute (default 0), second (default 0), millisecond (default 0), utc (default false) | Returns a datetime object, like the ones used by the functions above. | | dt.time | function | hour (default 0), minute (default 0), second (default 0), millisecond (default 0) | Returns a time object. | | dt.timedelta | function | days (optional), seconds (optional), milliseconds (optional), minutes (optional), hours (optional), weeks (optional) | Returns a timedelta object. | | date | class | | The date class, which has static methods which can be called upon. | | datetime | class | | The datetime class, which has static methods which can be called upon. | | time | class | | The time class, which has static methods which can be called upon. | | timedelta | class | | The timedelta class, which has static methods which can be called upon. | ### To/From JSON | Name | Type | Arguments | Description | | ------------------------------------------------------------------------ | ------ | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [to_json](https://www.home-assistant.io/template-functions/to_json/) | filter | obj, ensure_ascii, pretty_print, sort_keys | Turn an object into a JSON string. `ensure_ascii` converts unicode characters into escape sequences. `pretty_print` formats the output with new lines and an indent of two spaces. `sort_keys` sorts the keys of the JSON object. | | [from_json](https://www.home-assistant.io/template-functions/from_json/) | filter | value | Parse a string as JSON. | ### Is Defined | Name | Type | Arguments | Description | | -------------------------------------------------------------------------- | ------ | --------- | -------------------------------------------------------------- | | [is_defined](https://www.home-assistant.io/template-functions/is_defined/) | filter | value | Returns the value if it is defined, otherwise throws an error. | ### Version | Name | Type | Arguments | Description | | -------------------------------------------------------------------- | ---------------- | --------- | --------------------------------- | | [version](https://www.home-assistant.io/template-functions/version/) | function, filter | version | Returns a SemanticVersion object. | ### Distance | Name | Type | Arguments | Description | | ---------------------------------------------------------------------- | ---------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [distance](https://www.home-assistant.io/template-functions/distance/) | function | args | Measures the distance between home, an entity, or coordinates. The unit of measurement (kilometers or miles) depends on the system’s configuration settings. | | [closest](https://www.home-assistant.io/template-functions/closest/) | function, filter | args | Finds the closest entity to home, or the first entity or coordinate if multiple provided. Arguments can be entity IDs, domains, entity state objects, coordinate pairs, or arrays. | ### Contains | Name | Type | Arguments | Description | | ---------------------------------------------------------------------- | ------------ | ----------- | ----------------------------------- | | [contains](https://www.home-assistant.io/template-functions/contains/) | filter, test | list, value | Returns if an element is in a list. | ### Numeric | Name | Type | Arguments | Description | | -------------------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [float](https://www.home-assistant.io/template-functions/float/) | function, filter | value, fallback (optional) | Converts a value to a float. If that fails, it returns the fallback value or, if omitted, raises an error. | | [is_number](https://www.home-assistant.io/template-functions/is_number/) | function, filter | value | Returns true if a value can be parsed as a number. | | [int](https://www.home-assistant.io/template-functions/int/) | function, filter | value, fallback (optional) | Converts a value to an integer. If that fails, it returns the fallback value or, if omitted, raises an error. | | [bool](https://www.home-assistant.io/template-functions/bool/) | function, filter | value, fallback (optional ) | Converts a value to a boolean based on the human readable truthiness of it, case insensitive. Non-zero integers, `true`, `yes`, `on`, `enable`, and `1` return true. 0, `false`, `no`, `off`, `disable` and `0` return false. If the value's human readable truthiness cannot be determined, returns the fallback value or, if omitted, raises an error. | | [log](https://www.home-assistant.io/template-functions/log/) | function, filter | value, base (default e), fallback (optional) | Returns the logarithm of a value, defaulting to the natural logarithm if no base is provided. If that fails, it returns the fallback value or, if omitted, raises an error. | | [sin](https://www.home-assistant.io/template-functions/sin/) | function, filter | value, fallback (optional) | Returns the sine of a value. If that fails, it returns the fallback value or, if omitted, raises an error. | | [cos](https://www.home-assistant.io/template-functions/cos/) | function, filter | value, fallback (optional) | Returns the cosine of a value. If that fails, it returns the fallback value or, if omitted, raises an error. | | [tan](https://www.home-assistant.io/template-functions/tan/) | function, filter | value, fallback (optional) | Returns the tangent of a value. If that fails, it returns the fallback value or, if omitted, raises an error. | | [asin](https://www.home-assistant.io/template-functions/asin/) | function, filter | value, fallback (optional) | Returns the arcus sine of a value. If that fails, it returns the fallback value or, if omitted, raises an error. | | [acos](https://www.home-assistant.io/template-functions/acos/) | function, filter | value, fallback (optional) | Returns the arcus cosine of a value. If that fails, it returns the fallback value or, if omitted, raises an error. | | [atan](https://www.home-assistant.io/template-functions/atan/) | function, filter | value, fallback (optional) | Returns the arcus tangent of a value. If that fails, it returns the fallback value or, if omitted, raises an error. | | [atan2](https://www.home-assistant.io/template-functions/atan2/) | function, filter | y, x, fallback (optional) | Returns the four quadrant arcus tangent of y / x. If that fails, it returns the fallback value or, if omitted, raises an error. | | [sqrt](https://www.home-assistant.io/template-functions/sqrt/) | function, filter | value, fallback (optional) | Returns the square root of a value. If that fails, it returns the fallback value or, if omitted, raises an error. | | [max](https://www.home-assistant.io/template-functions/max/) | function, filter | args | Returns the largest argument provided, flattening any arrays. | | [min](https://www.home-assistant.io/template-functions/min/) | function, filter | args | Returns the smallest argument provided, flattening any arrays. | | [average](https://www.home-assistant.io/template-functions/average/) | function, filter | values, fallback (optional) | Returns the average of an array, flattening any subarrays. If a non-numeric value is detected or the array is empty, it returns the fallback value or, if omitted, raises an error. | | [median](https://www.home-assistant.io/template-functions/median/) | function, filter | values, fallback (optional) | Returns the median of an array, flattening any subarrays. If a non-numeric value is detected or the array is empty, it returns the fallback value or, if omitted, raises an error. | | [statistical_mode](https://www.home-assistant.io/template-functions/statistical_mode/) | function, filter | values, fallback (optional) | Returns the mode of an array, flattening any subarrays. If a non-numeric value is detected or the array is empty, it returns the fallback value or, if omitted, raises an error. | | [clamp](https://www.home-assistant.io/template-functions/clamp/) | function, filter | value, min, max | Limits a value to be between min and max, clamping at the edges. If an input is not a number an error is raised. | | mod | function, filter | n, m | Performs the mathematical modulo operation on two numbers. Raises an error if the second number is 0. | | [wrap](https://www.home-assistant.io/template-functions/wrap/) | function, filter | value, min, max | Limits a value to be between min and max, wrapping at the edges. If an input is not a number an error is raised. | | [remap](https://www.home-assistant.io/template-functions/remap/) | function, filter | value, in_min, in_max, out_min, out_max, steps (default 0), edges (default none) | Remaps a value from the input range to the output range. If the value or range inputs are not a number an error is raised. You can optionally set the `steps` parameter to a positive integer to quantize the output to a number of descrete steps. You can optionally set the `edges` parameter to control how out-of-bounds inputs values are handled. `edges='clamp'` will clamp the output to the min/max output range. `edges='wrap'` will wrap the input value around the input range before remapping. `edges='mirror'` will bounce the input value back and forth within the input range before remapping. | | [e](https://www.home-assistant.io/template-functions/e/) | constant | | Mathematical constant Euler's number. | | [pi](https://www.home-assistant.io/template-functions/pi/) | constant | | Mathematical constant pi. | | [tau](https://www.home-assistant.io/template-functions/tau/) | constant | | Mathematical constant tau. | | inf | constant | | Mathematical conceptual value infinity. | | [round](https://www.home-assistant.io/template-functions/round/) | filter | value, precision, method, fallback (optional) | Converts the input to a number and rounds it to `precision` decimals. It has four modes - `even`, `floor`, `ceil`, and `half`. If the input value is not a number, it returns the fallback value, or, if omitted, raises an error. | | [bitwise_and](https://www.home-assistant.io/template-functions/bitwise_and/) | filter | value_one, value_two | Performs a bitwise and(&) operation with two values. | | [bitwise_or](https://www.home-assistant.io/template-functions/bitwise_or/) | filter | value_one, value_two | Performs a bitwise or(\|) operation with two values. | | [bitwise_xor](https://www.home-assistant.io/template-functions/bitwise_xor/) | filter | value_one, value_two | Performs a bitwise xor(^) operation with two values. | | bitwise_not | filter | value | Performs a bitwise not(~) operation with one value. | | [ord](https://www.home-assistant.io/template-functions/ord/) | filter | value | Returns an integer representing a character's (string of length one) Unicode code point. | | [multiply](https://www.home-assistant.io/template-functions/multiply/) | filter | value, arg | Converts the input to a number and multiplies it by the argument. | | [add](https://www.home-assistant.io/template-functions/add/) | filter | value, arg | Converts the input to a number and adds it to the argument. | ### Complex Type Checking | Name | Type | Arguments | Description | | ------------------------------------------------------------ | ---- | --------- | -------------------------------------------------- | | list | test | value | Tests if a value is a list/array. | | [set](https://www.home-assistant.io/template-functions/set/) | test | value | Tests if a value is a set. | | datetime | test | value | Tests if a value is a datetime. | | string_like | test | value | Tests if a value is a string, bytes, or bytearray. | ### Type Conversions | Name | Type | Arguments | Description | | --------------------------------------------------------------- | ---------------- | --------- | ------------------------------------------------------ | | [set](https://www.home-assistant.io/template-functions/set/) | function | args | Convert a list/array to a set. Removes duplicates. | | [list](https://www.home-assistant.io/template-functions/list/) | function | args | Convert a set to an array. Does not remove duplicates. | | [str](https://www.home-assistant.io/template-functions/string/) | function, filter | value | Return the string representation of the input. | ### Iterating Multiple Objects | Name | Type | Arguments | Description | | ------------------------------------------------------------ | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------- | | [zip](https://www.home-assistant.io/template-functions/zip/) | function | args | Use to iterate over multiple collections in one operation. If given one array will perform the opposite action and unzip the list. | ### Function and Filters to Process Raw Data | Name | Type | Arguments | Description | | ------------------------------------------------------------------ | ---------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [pack](https://www.home-assistant.io/template-functions/pack/) | function, filter | data, format_string | Convert a native type to a bytes type object. | | [unpack](https://www.home-assistant.io/template-functions/unpack/) | function, filter | data, format_string, offset (default 0) | Convert a byte types object into a native object. The `offset` parameter defines the offset position in bytes from the start of the input bytes based buffer. | ### String filters | Name | Type | Arguments | Description | | -------------------------------------------------------------------------------- | ------ | ----------------------------- | -------------------------------------------------------------------------------------------------------- | | [urlencode](https://www.home-assistant.io/template-functions/urlencode/) | filter | value | Convert an object to a percent-encoded ASCII text string. | | [slugify](https://www.home-assistant.io/template-functions/slugify/) | filter | value, separator (default \_) | Convert a given string into a "slug". | | [ordinal](https://www.home-assistant.io/template-functions/ordinal/) | filter | value | Convert an integer into a number defining a position in a series (e.g. `1st`, `2nd`, `3rd`, `4th`, etc). | | [from_hex](https://www.home-assistant.io/template-functions/from_hex/) | filter | value | Decodes a hex string to raw bytes. | | [base64_encode](https://www.home-assistant.io/template-functions/base64_encode/) | filter | value | Encodes a string or bytes to a base 64 string. | | [base64_decode](https://www.home-assistant.io/template-functions/base64_decode/) | filter | value | Decodes a base 64 string to a UTF-8 string. | ### Hashing | Name | Type | Arguments | Description | | ------------------------------------------------------------------ | ---------------- | --------- | ------------------------- | | [md5](https://www.home-assistant.io/template-functions/md5/) | function, filter | value | Hash value to md5 hex. | | [sha1](https://www.home-assistant.io/template-functions/sha1/) | function, filter | value | Hash value to sha1 hex. | | [sha256](https://www.home-assistant.io/template-functions/sha256/) | function, filter | value | Hash value to sha256 hex. | | [sha512](https://www.home-assistant.io/template-functions/sha512/) | function, filter | value | Hash value to sha512 hex. | ### Regular Expressions **NOTE**: The format of regular expressions in nunjucks is different than jinja2. You may want to read the [Nunjucks](https://mozilla.github.io/nunjucks/templating.html#regular-expressions) and [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) documentation. | Name | Type | Arguments | Description | | -------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | [match](https://www.home-assistant.io/template-functions/match/) | test | value, find | Matches the find string at the beginning of the value string using regex. | | [search](https://www.home-assistant.io/template-functions/search/) | test | value, find | Matches the find string anywhere in the value string using regex. | | test | test | value, find | Matches the find regular expression in the value string using regex. Regular expressions should be preceded by r, like `r/foobar/g`. | | [regex_replace](https://www.home-assistant.io/template-functions/regex_replace/) | filter | value, find (default ''), replace (default '') | Replaces the find expression with the replace expression string using RegEx. | | [regex_findall](https://www.home-assistant.io/template-functions/regex_findall/) | filter | value, find (default '') | Finds all RegEx matches of the find expression in value and returns an array of matches. | | [regex_findall_index](https://www.home-assistant.io/template-functions/regex_findall_index/) | filter | value, find (default ''), index (default 0) | Performs a RegEx find all but returns the match at a provided index. | ### Shuffling | Name | Type | Arguments | Description | | -------------------------------------------------------------------- | ---------------- | ----------------------- | -------------------------------------------------------------- | | [shuffle](https://www.home-assistant.io/template-functions/shuffle/) | function, filter | values, seed (optional) | Shuffle an array, either using a random seed or providing one. | ### Flatten a List of Lists | Name | Type | Arguments | Description | | -------------------------------------------------------------------- | ---------------- | ------------------------- | ---------------------------------------------------------------------------------------------------- | | [flatten](https://www.home-assistant.io/template-functions/flatten/) | function, filter | values, levels (optional) | Flatten a list of lists. The depth of the flattening can be controlled using the `levels` parameter. | ### Find Common Elements Between Lists | Name | Type | Arguments | Description | | ------------------------------------------------------------------------ | ---------------- | ------------ | ----------------------------------------- | | [intersect](https://www.home-assistant.io/template-functions/intersect/) | function, filter | list1, list2 | Finds comment elements between two lists. | ### Find Elements In First List Not In Second List | Name | Type | Arguments | Description | | -------------------------------------------------------------------------- | ---------------- | ------------ | ---------------------------------------------------------------------- | | [difference](https://www.home-assistant.io/template-functions/difference/) | function, filter | list1, list2 | Finds elements that are in the first list but not in the secondc list. | ### Find Elements That Are In Either List But Not In Both | Name | Type | Arguments | Description | | ---------------------------------------------------------------------------------------------- | ---------------- | ------------ | --------------------------------------------------------------------- | | [symmetric_difference](https://www.home-assistant.io/template-functions/symmetric_difference/) | function, filter | list1, list2 | Finds elements that are in either of the input lists but not in both. | ### Combine All Unique Elements From Two Lists | Name | Type | Arguments | Description | | ---------------------------------------------------------------- | ---------------- | ------------ | ------------------------------------------- | | [union](https://www.home-assistant.io/template-functions/union/) | function, filter | list1, list2 | Combine all unique elements from two lists. | ### Combining Dictionaries | Name | Type | Arguments | Description | | -------------------------------------------------------------------- | ---------------- | --------- | ---------------------------- | | [combine](https://www.home-assistant.io/template-functions/combine/) | function, filter | ...dicts | Merge multiple dictionaries. | ### Working With Macros | Name | Type | Arguments | Description | | ---------------------------------------------------------------------------- | ------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [map](https://www.home-assistant.io/template-functions/map/) | filter | arr, function, ...args | Call a function on every item in an array and return the resulting array. | | [apply](https://www.home-assistant.io/template-functions/apply/) | filter, test | value, function, ...args | Apply a function to a value. Useful for calling other functions within other filters | | [as_function](https://www.home-assistant.io/template-functions/as_function/) | filter | macro | Convert a macro to a function to preserve underlying datatypes. The macro's first argument must be the callable parameter returns, which is silently called within the macro using `{%- set _ = returns(return_value) -%}`. | ### Merge Action Responses | Name | Type | Arguments | Description | | ---------------------------------------------------------------------------------- | -------- | --------- | ------------------------------------------- | | [merge_response](https://www.home-assistant.io/template-functions/merge_response/) | function | value | Merge several responses into a single array | ### Determining Types | Name | Type | Arguments | Description | | ------------------------------------------------------------------ | ---------------- | --------- | --------------------------------------------- | | [typeof](https://www.home-assistant.io/template-functions/typeof/) | function, filter | value | Returns the closest Python type of the input. | ### Miscellaneous Functions that are not from or related to functions in the Home Assistant templating documentation. | Name | Type | Arguments | Description | | ----------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | match_media | function | value | Returns the boolean result of the provided [CSS media query](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries). | [last-commit-shield]: https://img.shields.io/github/last-commit/Nerwyn/ha-nunjucks?style=for-the-badge [commits]: https://github.com/Nerwyn/ha-nunjucks/commits/main [forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg?style=for-the-badge [forum]: https://community.home-assistant.io/t/an-easy-way-to-add-templating-support-to-your-custom-front-end-projects/651621 [license-shield]: https://img.shields.io/github/license/Nerwyn/ha-nunjucks.svg?style=for-the-badge [maintenance-shield]: https://img.shields.io/badge/maintainer-Nerwyn-blue.svg?style=for-the-badge [github]: https://img.shields.io/github/followers/Nerwyn.svg?style=social --- _Source: https://npm.io/package/ha-nunjucks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._