Timer

The Timer integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] lets you create and manage countdown timers in Home Assistant.

You can use timers in automations and scripts to keep a bathroom fan running for 20 minutes, remind yourself when laundry is nearly done, or turn lights off after motion has stopped.

Configuration

The preferred way to create a timer is from the user interface. Go to Settings > Devices & services > Helpers, select Create helper, and then select Timer.

If you removed default_config: from your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more], add timer: first before creating timers from the UI.

You can also define timers in YAML. To add a timer, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
timer:
  laundry:
    duration: "00:01:00"

Configuration options

When you create or edit a timer from the UI, the following options are available.

Pick an icon from Material Design Icons and prefix it with mdi:.

Supported functionality

The Timer integration provides timer entities that you can use in dashboards, scripts, and automations.

Use a timer when you want a countdown that can be started, paused, changed, canceled, finished, shown on a dashboard, or reused across multiple automations. Unlike an automation’s for option, a timer is its own entity, so you can see it, manage it, and use the same countdown in more than one place. If you only need to wait until another trigger or condition stays true for a while, using that automation’s for option is often simpler.

• Timer entity
  • Description: Represents a countdown that you can start, pause, change, cancel, or finish.
  • States: idle, active, and paused.
  • Remarks: A timer returns to idle when it finishes, is canceled, or has not been started yet.

List of triggers

The Timer integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following triggers. Each link below opens a dedicated page with examples, fields, and a step-by-step UI walkthrough.

• Timer cancelled (timer.cancelled) Triggers when one or more timers are cancelled.

• Timer finished (timer.finished) Triggers when one or more timers finish.

• Timer paused (timer.paused) Triggers when one or more timers are paused.

• Timer restarted (timer.restarted) Triggers when one or more timers are restarted.

• Timer started (timer.started) Triggers when one or more timers are started.

• Timer time remaining (timer.time_remaining) Triggers when one or more timers reach a specific remaining time.

For an overview of every trigger across all integrations, see the triggers reference.

List of conditions

The Timer integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following conditions. Each link below opens a dedicated page with examples, fields, and a step-by-step UI walkthrough.

• Timer is active (timer.is_active) Tests if one or more timers are active.

• Timer is idle (timer.is_idle) Tests if one or more timers are idle.

• Timer is paused (timer.is_paused) Tests if one or more timers are paused.

For an overview of every condition across all integrations, see the conditions reference.

Actions

Action: Start

The timer.start action starts or restarts a timer with the provided duration. If no duration is given, it will either restart with its initial value, or continue a paused timer with the remaining duration. If a new duration is provided, this will be the duration for the timer until it finishes or is canceled, which then will reset the duration back to the original configured value. The duration can be specified as a number of seconds or the easier to read 01:23:45 format. You can also use entity_id: all and all active timers will be started.

Action: Change

The timer.change action changes an active timer. This changes the duration of the timer with the duration given. You can also use entity_id: all and all active timers will be changed. You cannot extend the duration beyond that set by timer.start.

Action: Pause

The timer.pause action pauses a running timer. This will retain the remaining duration for later continuation. To resume a timer use the timer.start action without passing a duration. You can also use entity_id: all and all active timers will be paused.

Action: Cancel

The timer.cancel action cancels a running or paused timer. This resets the duration to the last known initial value without firing the timer.finished event. You can also use entity_id: all and all active and paused timers will be canceled.

Action: Finish

The timer.finish action manually finishes a running or paused timer earlier than scheduled. You can also use entity_id: all and all active and paused timers will be finished.

Action: Reload

The timer.reload action reloads timer’s configuration without restarting Home Assistant itself. This action takes no data attributes.

Using the action

Go to Settings > Developer tools > Actions and select the timer.start action, then click the Fill Example Data button. Now change the entity_id and duration and select Perform action button.

Timer automation examples

Automation: turn off the bathroom fan when the timer finishes

Use a timer to keep the fan running for a fixed amount of time after a shower.

• Trigger: Timer finished
  • Target: Bathroom fan timer
  • Trigger when: Each
• Action: Turn off fan

alias: "Turn off bathroom fan when the timer finishes"
triggers:
  - trigger: timer.finished
    target:
      entity_id: timer.bathroom_fan
actions:
  - action: fan.turn_off
    target:
      entity_id: fan.bathroom

Automation: send a reminder when only five minutes remain

Get a reminder shortly before a timer finishes, like when laundry or cooking time is almost done.

• Trigger: Timer time remaining
  • Target: Laundry timer
  • Time remaining: 00:05:00
• Action: Send a notification message
  • Target: My Device (notify.my_device)

alias: "Notify when five minutes remain on the laundry timer"
triggers:
  - trigger: timer.time_remaining
    target:
      entity_id: timer.laundry
    options:
      remaining: "00:05:00"
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      message: "The laundry timer has five minutes left."

Known limitations

• If a timer finishes while Home Assistant is not running, automations that use the Timer finished trigger do not run after startup.

Removing the integration

To remove a timer created from the UI, go to Settings > Devices & services > Helpers, select the timer, and delete it.

If you configured a timer in YAML, remove it from your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file and reload or restart Home Assistant.