https://github.com/denysdovhan/ha-template
A tiny (<2kB) lit component for rendering templates in Home Assistant custom cards
https://github.com/denysdovhan/ha-template
custom-cards home-assistant homeassistant jinja2 lit lit-element lovelace
Last synced: 3 months ago
JSON representation
A tiny (<2kB) lit component for rendering templates in Home Assistant custom cards
- Host: GitHub
- URL: https://github.com/denysdovhan/ha-template
- Owner: denysdovhan
- License: mit
- Created: 2022-04-18T14:05:16.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-03-15T21:32:40.000Z (3 months ago)
- Last Synced: 2025-03-18T02:11:41.211Z (3 months ago)
- Topics: custom-cards, home-assistant, homeassistant, jinja2, lit, lit-element, lovelace
- Language: TypeScript
- Homepage:
- Size: 2.6 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://stand-with-ukraine.pp.ua/)
# Home Assistant Template Component
[![npm version][npm-image]][npm-url]
[![Patreon][patreon-image]][patreon-url]
[![Buy Me A Coffee][buymeacoffee-image]][buymeacoffee-url]
[![Twitter][twitter-image]][twitter-url]
> A tiny (<2kB) lit component for rendering templates in [Home Assistant][home-assistant] custom cards
`ha-template` is a tiny Lit component that conveniently handles rendering templates in [Home Assistant][home-assistant] custom cards. It subscribes to template updates, automatically rerenders them along with the template value and displays a fallback value if template is not available.
## Installing
**💡 Tip:** If you like this project, consider becoming a patron:
or just buy me a cup of ☕️ or 🥤:
Install this utility as any other dependency:
```sh
npm install -S ha-template
# or
yarn add ha-template
```
## Usage
Use `ha-template` in your card by importing and registering it as a custom component.
Pass `hass` object, `template` string and optional falback `value`. `ha-template` will handle template rendering and updating automatically.
```js
import registerTemplates from 'ha-template';
// Register ha-template component.
// You can pass custom component name, if you want so.
registerTemplates();
class MyCustomCard extends LitElement {
static get properties() {
return {
hass: Object,
config: Object,
};
}
setConfig(config) {
this.config = config;
}
render() {
const value_template = this.config;
const fallback = 'Unknown';
// Use in your card.
//
// Pass hass object, template and a fallback value.
// Fallback value will replace with the result of rendered template.
// If template is not defined, fallback value will be used.
return html`
`;
}
}
```
Alternatively, you can register `HATemplate` as a custom element on your own:
```js
import { HATemplate } from 'ha-template';
// Register HATemplate as a custom element.
customElements.define(component, HATemplate);
```
## API
`ha-template` has two exports:
2. `HATemplate` - a custom lit-component that provides a convenient way to render templates. You can import it and register it as a custom element.
1. `default` - a function that registers `HATemplate` as a `ha-tempalte` custom element, by default. You can pass custom component name, if you want so.
`HATemplate` component accepts these properties:
1. `hass` - an object of Home Assistant connection.
2. `template` - a string that contains a [Jinja2](https://palletsprojects.com/p/jinja) template.
3. `value` - a fallback value that will be used if template is not defined. Will be replaced by template result.
4. `variables` - an object of custom variables to be used within the template.
## Development
Want to contribute to the project?
First of all, thanks! Check [contributing guideline](./CONTRIBUTING.md) for more information.
## License
MIT © [Denys Dovhan][denysdovhan]
[npm-url]: https://npmjs.org/package/ha-template
[npm-image]: https://img.shields.io/npm/v/ha-template.svg?style=flat-square
[patreon-url]: https://patreon.com/denysdovhan
[patreon-image]: https://img.shields.io/badge/support-patreon-F96854.svg?style=flat-square
[buymeacoffee-url]: https://patreon.com/denysdovhan
[buymeacoffee-image]: https://img.shields.io/badge/support-buymeacoffee-222222.svg?style=flat-square
[twitter-url]: https://twitter.com/denysdovhan
[twitter-image]: https://img.shields.io/badge/twitter-%40denysdovhan-00ACEE.svg?style=flat-square
[home-assistant]: https://www.home-assistant.io/
[denysdovhan]: https://denysdovhan.com