Home Assistant Best Practices

Home Assistant Best Practices

Core principle: Use native Home Assistant constructs wherever possible. Templates bypass validation, fail silently at runtime, and make debugging opaque.

No tool reaches the HA API? Do not stop to ask for access. If you can drive a browser on the HA web UI, make the change there, but first show the user the exact change and wait for their OK before you save: approving a click does not show them what it writes. Otherwise give the user the complete config to create in the UI (for an automation, the YAML for the editor's Edit in YAML mode; for a helper, its form fields), and name the entity IDs you assumed. Config that can only be written in YAML is edited with the File editor app (or in the config folder on a Container install): keep a copy of the file first, then check the configuration and run the matching reload in the YAML tab of Tools (named Developer Tools before 2026.8; restart if it isn't listed).

A feature marked with a release (2026.5+) depends on the instance's version. Read it before choosing: version in GET /api/config, or Settings → About in the UI. On that release or later, use the feature and do not offer the older way as an equal choice. If you cannot read the version, assume a current release and name the older fallback with the version it needs.

Read the matching reference before you answer. This page only summarizes the files in Reference Files; the exact keys, fields and working examples are in them. Read every file whose row matches the task, and only those: do not load all reference files upfront.

Decision Workflow

Follow this sequence when creating any automation:

0. Gate: modifying existing config?

If your change affects entity IDs, display names, or cross-component references — renaming entities or devices, replacing template sensors with helpers, converting device triggers, or restructuring automations — read safe-refactoring first. That reference covers impact analysis, device-sibling discovery, display-name overrides, and post-change verification. Complete its workflow before proceeding.

Steps 1-5 below apply to new config or pattern evaluation.

1. Check for a purpose-specific, then generic native, trigger/condition

Since 2026.7 the default building blocks are purpose-specific triggers/conditions — <domain>.<name> keys (motion detected, battery low, door opened) with area/floor/label targets. Check for one that matches the intent first, then a generic native trigger/condition, and only then a template. Read triggers-and-conditions #purpose-specific-triggers--conditions-default-since-20267 before writing the trigger.

A purpose-specific trigger takes entity_id in its target: as well, so one known sensor is not a reason to fall back to trigger: state. Write the automation with the purpose-specific trigger; do not offer it only as an optional upgrade.

Common substitutions:

• trigger: state on a motion, occupancy or door binary_sensor → motion.detected/motion.cleared, occupancy.detected/occupancy.cleared or door.opened/door.closed with target: {entity_id: ...}, or area_id when the area is known
• List of individual sensor entities in a trigger → one purpose-specific trigger with an area/floor/label target:
• delay after motion.detected for "no motion anywhere for N minutes" → motion.cleared with options: {behavior: all, for: ...}, which fires once every targeted sensor has been clear that long (unavailable and unknown sensors are left out of the count)
• {{ states('x') | float > 25 }} → numeric_state condition with above: 25
• {{ is_state('x', 'on') and is_state('y', 'on') }} → condition: and with state conditions
• {{ now().hour >= 9 }} → condition: time with after: "09:00:00"
• wait_template: "{{ is_state(...) }}" → wait_for_trigger with state trigger (caveat: different behavior when state is already true — see safe-refactoring #trigger-restructuring)

2. Check for built-in helper or Template Helper

Read helper-selection before creating a template sensor.

Common substitutions:

• Sum/average multiple sensors → min_max integration
• Binary any-on/all-on logic → group helper
• Rate of change → derivative integration
• Cross threshold detection → threshold integration
• Consumption tracking → utility_meter helper

If no built-in helper fits, use a Template Helper — not YAML. Create it via the HA config flow (programmatically or in the UI: Settings → Devices & Services → Helpers → Create Helper → Template). A flow-created helper is UI-editable; a template: YAML entry needs a template.reload and is not.

Write template: YAML when the user asks for it, when neither path is available, or when the config needs a key the flow has no field for — trigger-based templates and attributes: are the common ones. Then use managed YAML editing (yaml-only-integrations), not a hand-edit.

3. Select correct automation mode

Default single mode is often wrong. See automation-actions #automation-modes.

4. Use entity_id over device_id

device_id breaks when devices are re-added. See device-control.

Exception: Zigbee2MQTT autodiscovered device triggers are acceptable.

5. For buttons and remotes

• Any integration exposing an event.* entity: Use event.received targeting that entity (see the anti-pattern row below)
• ZHA: No event entities — use an event trigger with device_ieee (persistent)
• Z2M: Event entities are experimental and off by default — use a device trigger (autodiscovered) or mqtt trigger

Read device-control #buttonremote-patterns before writing the trigger.

Critical Anti-Patterns

Reference Files

Read each file whose row matches the task before you answer: