Skip to main content

Using Eta.js Templates

Editor for ESPHome uses the Eta.js templating engine to dynamically generate YAML.
This makes it possible to avoid repetition, keep your configs modular, and build reusable building blocks for your devices.

Why Templates?​

ESPHome YAML can get repetitive fast.
With templates you can:

  • Reuse blocks of code across devices
  • Dynamically change values (IDs, names, pins)
  • Use conditions and loops to generate many similar components
  • Keep large configs clean and maintainable

File Extension​

Eta templates must use the .eta extension. When the editor builds the final config:

  • .eta files are rendered into YAML
  • Variables and logic inside them are processed
  • The generated YAML is merged with other files

Example​

Let's look at an example that will explain the usage of Eta templating

my-device/
├── .lib/
|   ├── inputs.eta
|   └── header.eta
└── device.eta
binary_sensor:
<% for (let i = 0; i < it.count; i++) { %>
  - platform: gpio
    pin: <%= i %>
    name: "Input <%= i %>"
<% } %>

Basic Syntax​

Eta uses JavaScript syntax inside special tags:

  • <% ... %> — execute JavaScript code (no output)
  • <%= ... %> — evaluate and print a value

Loops​

Loops are especially useful when generating multiple sensors, switches, or pins.

binary_sensor:
<% for (let i = 0; i < 4; i++) { %>
  - platform: gpio
    pin: <%= i %>
    name: "Input <%= i %>"
<% } %>

Conditionals​

You can include YAML conditionally based on variables:

<% if (it.debug) { %>
logger:
  level: DEBUG
<% } else { %>
logger:
  level: WARN
<% } %>

Includes and Reuse​

You can split templates into smaller files and include them where needed.
For shared code, store files in device or global .lib/ and import them whenever needed.

  • <%~ include('./.lib/file', { key: value }) %>
    • imports from devices .lib folder
  • <%~ include('./../.lib/file', { key: value }) %>
    • imports from global .lib folder

Best Practices​

  • ✅ Keep logic simple — use Eta for structure, not business logic
  • ✅ Group related components into their own template files
  • ✅ Use .lib/ for shared templates across devices
  • ✅ Comment your templates for clarity
  • ❌ Avoid overly complex JavaScript — configs should stay easy to read

Next Steps​