Numeric state crossed threshold

The Numeric state crossed threshold trigger is a general trigger for reacting when a numeric value crosses a threshold. Use it when you need to watch an exact numeric state or attribute value, or when the visual automation editor does not offer a trigger named after what you want to watch.

If the visual automation editor shows a trigger named after the measurement you care about, use that one instead. For example, use Temperature crossed threshold for temperature readings or Power crossed threshold for power readings. These triggers are easier to read later and can handle compatible units automatically.

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. Search for and select the Numeric state crossed threshold trigger.
5. In Entity, select the entity whose numeric value Home Assistant should watch.
6. Optional: Select Add entity to select additional entities whose numeric value Home Assistant should watch.
7. Optional: In Attribute, select an attribute instead of the main state.
8. In Above, enter a number to fire the trigger only if the value of the numeric state or attribute is above that number. Instead of a Fixed number, you can select Value of an entity and then select an entity from the list. This fires the trigger if the value of the numeric state or attribute is above the value of the selected entity.
9. In Below, enter a number to fire the trigger only if the value of the numeric state or attribute is below that number. Instead of a Fixed number, you can select Value of an entity and then select an entity from the list. This fires the trigger if the value of the numeric state or attribute is below the value of the selected entity.
10. Set Above, Below, or both. If you set both, the trigger reacts when the value of the numeric state or attribute enters the range between them.
11. Optional: In Value template, enter a template that will be used to calculate the numeric value.
12. Optional: In For at least, enter how long the numeric state or attribute value must remain unchanged or stay within the configured threshold before the trigger fires. You can enter a template by selecting Template instead of Duration.
13. 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. For how an automation is built in YAML, refer to Automations in YAML.

When this trigger starts an automation, it passes data about what happened to the automation. You can use this trigger data in the templates of your conditions and actions. To see which data is available, refer to Trigger data in templates.

In YAML, use trigger: numeric_state. A basic example looks like this:

trigger: numeric_state
entity_id: sensor.outdoor_temperature
above: 30

This runs when the outdoor temperature crosses from 30 or below to above 30.

Options in YAML

Targets of the trigger

This trigger watches one or more entities selected in the UI options Entity and Add entity, or using the entity_id option in YAML. Each selected entity must provide a numeric state, or a numeric value in the attribute you choose.

• Use a single Entity (entity_id) to watch one entity.
• Select Add entity, or a list of entity_id values in YAML, to watch more than one entity.

Good to know

• This trigger fires when a value crosses a threshold. It does not keep firing while the value stays on the same side of the threshold.
• If you set both Above and Below, the trigger fires when the value enters that range.
• This trigger compares the raw numeric value you enter. It does not convert between units. For measurements with units, use a trigger named after that measurement when one is available.
• If you use an entity in Above (above) or Below (below), Home Assistant compares the value of the watched entity against the value of that entity only when the watched entity updates.
• If you use For at least (for), the timer resets if Home Assistant restarts or automations reload.
• When you use value_template, the state variable is the state object for the entity you selected with entity_id.

Try it yourself

Ready to test this? Go to Settings > Automations & scenes, create a new automation, and add this trigger. Save the automation, and then make the trigger react. For example, change the state of the targeted entityAn 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], turn on a light that the trigger monitors, or change its brightness. To check whether the automation ran, open its traces.

More examples

Real scenarios where this trigger fires in automations and scripts. Copy any example and adapt it to your setup. In the visual editor, select the UI options listed in the example when they are available, or paste the YAML code.

Automation: send a notification when the freezer gets too warm

If the freezer temperature rises above a safe value, this automation sends a message to your phone.

• Trigger: Numeric state crossed threshold
  • Entity: Freezer temperature sensor (sensor.freezer_temperature)
  • Above: -10
• Action: Send a notification message
  • Target: My Device (notify.my_device)

alias: "Alert when the freezer gets too warm"
triggers:
  - trigger: numeric_state
    entity_id: sensor.freezer_temperature
    above: -10
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      message: "The freezer temperature is above -10°C."

Automation: remind me when battery level stays low for 30 minutes

If a battery-powered device stays below a set level for a while, this automation reminds you to charge or replace it.

• Trigger: Numeric state crossed threshold
  • Entity: Door lock battery sensor (sensor.front_door_lock_battery)
  • Below: 20
  • For at least: 30 minutes
• Action: Send a notification message
  • Target: My Device (notify.my_device)

alias: "Remind me when the door lock battery stays low"
triggers:
  - trigger: numeric_state
    entity_id: sensor.front_door_lock_battery
    below: 20
    for: "00:30:00"
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      message: "The front door lock battery has been below 20% for 30 minutes."

Still stuck?

To find out why the trigger didn’t react, make the change that it should react to, and then open the traces of the automation. If the automation didn’t run, there’s usually no trace, but some triggers record a Did not trigger trace. For details, refer to Testing automations. For common problems and their solutions, refer to Troubleshooting automations.

If that doesn’t help, 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

Explore related triggers:

• State changed: Triggers when the state or an attribute changes.

• Time: Triggers at a specific time, or from a date/time helper or timestamp-style sensor.