Zone occupancy detected

The Zone occupancy detected trigger fires when a selected zone changes from empty to occupied. Use it when the automation only needs to know that at least one person is now in the zone, instead of reacting to each specific person or device tracker.

Using this trigger from the user interface

If you prefer building automations visually, Home Assistant walks you through this trigger step by step. You pick what to watch, tweak a few options, and save. No YAML knowledge required.

To use this trigger in an automation:

1. Go to Settings > Automations & scenes.
2. Open an existing automation, or select Create automation > Create new automation.
3. In the When section, select Add trigger.
4. From the search box, search for and select Zone occupancy detected.
5. Under Zone, select the zone to monitor.
6. Under For at least, you can set how long the zone must stay occupied before the trigger fires. Leave it at zero to fire immediately.
7. Select Save.

Options in the UI

Using this trigger in YAML

If you work directly in YAML, or you want to know exactly what Home Assistant does under the hood, this section has the technical reference. It lists the field names you use in YAML, their types, and which ones are required.

In YAML, refer to this trigger as zone.occupancy_detected. A basic example looks like this:

trigger: zone.occupancy_detected
options:
  zone: zone.home

This fires when zone.home changes from empty to occupied.

Options in YAML

YAML sometimes provides additional options for more complex use cases that are not available through the UI.

Good to know

• A zone is occupied when its state is a number of 1 or higher.
• If the zone state is unknown or unavailable, Home Assistant does not treat the zone as occupied.
• This trigger fires when the zone changes from empty to occupied. It does not fire again while the zone stays occupied.
• To react when a zone becomes empty, use Zone occupancy cleared.

Try it yourself

Ready to test this? Go to Settings > Automations & scenes, create a new automation, and add this trigger. Save the automation, then change the state of the targeted entity to watch the trigger fire on your actual entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more].

More examples

Real scenarios where this trigger fires in automations and scripts. Copy any example and adapt it to your setup.

Automation: turn on the porch light when someone gets home at night

When the home zone becomes occupied after sunset, this automation turns on the porch light.

• Trigger: Zone occupancy detected
  • Zone: Home (zone.home)
• Condition: Sun is below horizon
• Action: Turn on light
  • Target: Porch light (light.porch)

alias: "Turn on the porch light when someone gets home"
triggers:
  - trigger: zone.occupancy_detected
    options:
      zone: zone.home
conditions:
  - condition: sun
    after: sunset
actions:
  - action: light.turn_on
    target:
      entity_id: light.porch

Automation: notify when someone arrives at the cabin

When the cabin zone becomes occupied, this automation sends a notification.

• Trigger: Zone occupancy detected
  • Zone: Cabin (zone.cabin)
• Action: Send a notification message
  • Target: My Device (notify.my_device)

alias: "Notify when someone arrives at the cabin"
triggers:
  - trigger: zone.occupancy_detected
    options:
      zone: zone.cabin
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      message: "Someone arrived at the cabin."

Still stuck?

The Home Assistant community is quick to help: join Discord for real-time chat, post on the community forum with the trigger you’re using and what you expected to happen, or share on our subreddit /r/homeassistant.

Related triggers

These triggers work well alongside this one:

• Zone occupancy cleared: Triggers when a zone changes from occupied to empty.

• Entered zone: Triggers when one or more people or device trackers enter a zone.