Skip to content
BranchesTags

Repository files navigation

Quick Timer

Add to Home Assistant hacs_badge GitHub Release License Buy me a beer

Quick Timer is an all-in-one custom integration for Home Assistant that lets you schedule one-time actions on any entity — complete with a built-in Lovelace card, visual countdown, progress bar, and multi-target support.

The Lovelace card is included and registers automatically — no separate frontend installation required.

Active timer with countdown and progress bar

📑 Quick Navigation

Features · Installation · Getting Started · Card Configuration · Services · FAQ · Troubleshooting

✨ Features
⏱️ One-time scheduling Relative delay (seconds / minutes / hours) or absolute time (HH:MM)
🎯 Multi-target actions Control multiple entities with a single timer — start_actions run immediately, finish_actions run when the countdown ends
🔧 Dynamic service discovery The card auto-discovers available services and fields for each entity
📊 Progress bar Visual progress synced with the backend
💾 Persistent timers Tasks survive HA restarts; missed tasks execute on startup
🔔 Notifications HA persistent + targeted mobile push on completion
🎨 Built-in Lovelace card Compact & full modes, 24 colors, badge countdown, configurable interactions
💉 Dialog injection Quick Timer panel inside entity more-info dialogs
📋 Overview card Dashboard card listing all active timers
🧠 History presets Remembers last 3 configs per entity
🆔 Task isolation Multiple independent timers per entity via unique task_id

Frontend translations

Card and more-info panel translations are loaded from custom_components/quick_timer/www/translations/. The built-in frontend languages are English (en), Slovak (sk), Dutch (nl), French (fr), and German (de). To add another language, copy en.json, translate its values, and save it under the lowercase Home Assistant language code. No JavaScript or Python registration is required.

Regional files such as pt-br.json are supported. If a regional file is not present, Quick Timer tries the base language (pt.json) and then English. Missing keys in any translation also fall back to English.

📦 Installation

HACS (Recommended)

  1. Open HACS → Integrations
  2. Menu (⋮) → Custom repositories
  3. Add https://github.com/jozefnad/homeassistant-quick_timer • Category: Integration
  4. Search Quick Timer → Download
  5. Restart Home Assistant

Manual

  1. Download from Releases
  2. Copy custom_components/quick_timer to your config/custom_components/
  3. Restart Home Assistant

The Lovelace card resource registers automatically — no manual setup needed.

🚀 Getting Started

  1. Settings → Devices & Services → + Add Integration → Quick Timer → Submit
  2. Add custom:quick-timer-card to any dashboard — it's available in the card picker immediately
  3. Configure targets and timer defaults in the visual editor

Quick YAML Example

type: custom:quick-timer-card
targets:
  - entity: light.living_room
    service: light.turn_off
    phase: finish
default_delay: 30
default_unit: minutes
mode: compact

Time Presets

Customize time presets in Settings → Devices & Services → Quick Timer → Configure (comma-separated values for seconds, minutes, hours).

🎨 Card Configuration

The visual editor handles everything — just add the card and configure through the UI.

Card settings panel    Multi-target configuration

📋 Full Configuration Reference

Card Options

Option Type Default Description
targets list [] Entity targets with service, data, and phase (start / finish)
name string auto Card display name
icon string auto Icon override
color string state Icon color — state, primary, accent, or any of 24 named colors
default_delay int 15 Default delay value
default_unit string minutes seconds / minutes / hours
default_time_mode string relative relative (delay) or absolute (specific time)
default_at_time string Default absolute time (HH:MM)
mode string compact compact (tile) or full
show_badge bool true Countdown badge on icon
show_progress_bar bool false Visual progress bar
inactive_style string dim none, dim, or grayscale
primary_info string name Top line: name, state, last-changed, none
secondary_info string timer Bottom line: timer, state, action, none
tap_action object toggle-timer toggle-timer, settings, none
hold_action object settings Hold behavior
icon_tap_action object settings Icon tap behavior
notify_ha bool false HA persistent notification
notify_devices list [] Mobile device IDs for push notifications

Target Object

Field Type Description
entity string Entity ID (light.living_room)
service string Service to call (light.turn_off)
data object Service data ({ brightness: 128 })
phase string finish (default) — when timer ends / start — immediately

Multi-Target Example

Turn lights on immediately, turn everything off after 2 hours:

type: custom:quick-timer-card
name: Movie Mode
default_delay: 2
default_unit: hours
show_progress_bar: true
targets:
  - entity: light.living_room
    service: light.turn_on
    data:
      brightness: 50
    phase: start
  - entity: media_player.tv
    service: media_player.turn_on
    phase: start
  - entity: light.living_room
    service: light.turn_off
    phase: finish
  - entity: media_player.tv
    service: media_player.turn_off
    phase: finish

Overview Card

All active timers in one place:

type: custom:quick-timer-overview-card
title: Active Timers

Inactive card state

🔧 Services

quick_timer.run_action

Schedule a timer with immediate (start) and delayed (finish) actions.

service: quick_timer.run_action
data:
  task_id: bedroom_lights_off
  delay: 30
  unit: minutes
  finish_actions:
    - service: light.turn_off
      target:
        entity_id: light.bedroom
  notify_ha: true
📋 All Parameters
Parameter Type Required Default Description
task_id string ❌ auto Unique task identifier. Enables multiple timers per entity.
finish_actions list ✅ Actions when timer ends. Each: { service, target, data }
start_actions list ❌ Actions executed immediately on start
delay int ✅* 15 Delay (1–86400). Required for relative mode.
unit string ❌ minutes seconds, minutes, hours
time_mode string ❌ relative relative or absolute
at_time string ❌ Target time (HH:MM). Required for absolute mode.
task_label string ❌ Label for overview card
notify_ha bool ❌ false HA notification on completion
notify_mobile bool ❌ false Push to all mobile devices
notify_devices list ❌ Specific device IDs
📝 More Examples

Absolute time:

service: quick_timer.run_action
data:
  task_id: night_routine
  time_mode: absolute
  at_time: "23:30"
  start_actions:
    - service: light.turn_on
      target:
        entity_id: light.hallway
      data:
        brightness: 30
  finish_actions:
    - service: light.turn_off
      target:
        entity_id: light.hallway
    - service: switch.turn_off
      target:
        entity_id: switch.tv_plug

Multi-target with label and notifications:

service: quick_timer.run_action
data:
  task_id: movie_night
  task_label: "Movie Night"
  delay: 2
  unit: hours
  start_actions:
    - service: light.turn_on
      target:
        entity_id: light.living_room
      data:
        brightness: 50
    - service: media_player.turn_on
      target:
        entity_id: media_player.tv
  finish_actions:
    - service: light.turn_off
      target:
        entity_id: light.living_room
    - service: media_player.turn_off
      target:
        entity_id: media_player.tv
  notify_ha: true

quick_timer.cancel_action

service: quick_timer.cancel_action
data:
  task_id: bedroom_lights_off
📋 Preferences Services

quick_timer.get_preferences

Retrieve saved preferences and history for an entity (or all entities if omitted).

Parameter Type Required Description
entity_id string ❌ Entity ID

quick_timer.set_preferences

Save preferences for an entity (used internally by the card).

Parameter Type Required Description
entity_id string ✅ Entity ID
preferences object ✅ Preferences data

📊 Monitoring Sensor

sensor.quick_timer_monitor provides real-time information about all active timers.

State: Number of active tasks.

Attribute Description
active_tasks All tasks with remaining_seconds, start_timestamp, end_timestamp
task_count Number of active tasks
preferences Stored user preferences per entity
presets Configurable time presets

Example automation:

trigger:
  - platform: numeric_state
    entity_id: sensor.quick_timer_monitor
    above: 0
action:
  - service: notify.mobile_app
    data:
      message: "You have {{ states('sensor.quick_timer_monitor') }} active tasks"

📱 Events
Event Key Data Description
quick_timer_task_started task_id, finish_actions, delay_seconds Timer started
quick_timer_task_completed task_id, success_count, error_count Timer finished
quick_timer_task_cancelled task_id, reason Timer cancelled

Example automation:

trigger:
  - platform: event
    event_type: quick_timer_task_completed
action:
  - service: notify.mobile_app
    data:
      message: "Timer '{{ trigger.event.data.task_id }}' — {{ trigger.event.data.success_count }} actions done"

❓ FAQ

Do I need to install the Lovelace card separately?

No. The card is bundled and registers automatically. When you remove the integration, the resource is cleaned up too.

Can I run multiple timers for the same entity?

Yes. Each card generates a unique card_id used as task_id. Multiple cards targeting the same entity have fully independent timers.

What happens after a Home Assistant restart?

All tasks are persisted. On startup, pending tasks are restored. Expired tasks execute immediately.

How does absolute time mode work?

Set time_mode: absolute and at_time: "HH:MM". If the time is in the past, it schedules for the next day.

How are notifications delivered?
  • notify_ha — HA persistent notification
  • notify_mobile — Push to all mobile devices
  • notify_devices — Push to specific devices (uses notify.send_message first, falls back to notify.mobile_app_*)

🐛 Troubleshooting

Problem Solution
Card not in picker Ensure the config entry exists, clear cache (Ctrl+F5), check browser console
Services not available Check Settings → Devices & Services → Quick Timer is loaded
Timer didn't run after restart Task must have finish_actions; check logs for "Executing missed task"

🤝 Contributing

Contributions are welcome! Open an issue or pull request.

Built with ❤️ in my spare time.
If Quick Timer saves you time, consider buying me a beer — it keeps the motivation going!

Buy me a beer

⭐ If you like this project, give it a star!

About

A powerful Home Assistant integration for quick, one-time delayed actions with an auto-injected UI into entity dialogs.

Topics

addonassistantcustom-carddelayhacshacs-integrationhasshassio-integrationhomehome-assistanthomeassistantscheduleschedulertasktimer

Resources

Readme
MIT license
Activity

Stars

53 stars

Watchers

4 watching

Forks

2 forks
Report repository

Releases

Packages

Contributors

Languages