HA Simple Timer Integration (+ Card)

A simple Home Assistant integration that turns entities on and off with a precise countdown timer and daily runtime tracking.

Configuration

✨ Key Features

🚀 Out-of-the-box, pre-packaged timer solution, eliminating manual creation of multiple Home Assistant entities, sensors, and automations.

🕐 Flexible Timer Control - Set countdown timers in seconds, minutes, hours, or days for any switch, input_boolean, light, fan, or climate entity

❄️ Native Climate Support - Point a timer straight at an A/C or heat pump and pick the mode it should run in, no helper entity, no automation

⚡ Default Timer - Automatically starts a countdown when the device is turned on manually (Auto-Off functionality)

📊 Daily Runtime Tracking - Automatically tracks and displays daily usage time

🔄 Smart Auto-Cancel - Timer automatically cancels if the controlled device is turned off externally

🎨 Professional Timer Card - Beautiful, modern UI with customizable timer buttons and real-time countdown

🔔 Notification Support - Optional notifications for timer start, finish, and cancellation events

🌙 Daily Usage Reset - Daily usage statistics reset automatically at a time you choose (midnight by default)

👆 Manual Usage Reset - Long-press the daily usage display to reset statistics manually

⏰ Delayed Start Timers - Turns devices ON when timer completes and keeps them on indefinitely until manually turned off

⏱️ Schedule Timer - Start a timer at a chosen time of day (one-shot or recurring on selected days). Survives restarts. Optional, enabled per-card.

➕ Extend Timer - Add time to actively running timers on the fly without restarting

🏠 Perfect For

• Water Heater Control - Manage boiler schedules
• Kitchen Timers - Control smart switches for appliances
• Garden Irrigation - Time watering systems
• Lighting Control - Automatic light timers
• Fan Control - Bathroom or ventilation fans
• A/C and Heat Pumps - Run a climate entity in a chosen mode and switch it off on time
• Any Timed Device - Universal timer for any switchable device

📦 Installation

HACS (Recommended)

Use this link to open the repository in HACS and click on Download

⚠️ If you previously added this integration as a custom repository in HACS, it's recommended to remove the custom entry and reinstall it from the official HACS store. You will continue to receive updates in both cases, but switching ensures you're aligned with the official listing and avoids potential issues in the future.

Manual Installation

1. Download the latest release from GitHub Releases
2. Extract the custom_components/simple_timer folder to your Home Assistant custom_components directory
3. Restart Home Assistant
4. Note: You do NOT need to add the dashboard resource manually. It is automatically registered when the integration starts.

That's it! The timer card is automatically installed and ready to use.

⚙️ Configuration

Add Integration Instance

1. Go to Settings → Devices & Services
2. Click "Add Integration"
3. Search for "Simple Timer"
4. Select the device you want to control (switch, light, fan, input_boolean, climate)
5. Give your timer instance a descriptive name (e.g., "Kitchen Timer", "Water Heater")
6. Climate entities only: choose the mode to use when turning on (Heat, Cool, Dry, …). The list comes from the entity itself, and only that mode is applied - the timer always switches the device off at the end
7. Choose notification entitiy (optional) - can be add more than one
8. Set the Daily Usage Reset Time (optional) - the time of day the daily usage counter goes back to zero. Defaults to 00:00 (midnight); set it to 06:00 if your tracking day starts in the morning
9. Check show seconds (optional) - display seconds in uasge time and notifications

A climate entity that offers no off mode cannot be selected - a timer that cannot turn the device off again would be worse than no timer.

Add Timer Card to Dashboard

1. Edit your dashboard
2. Add a card
3. Search for "Simple Timer Card" (should appear in the card picker)
4. Configure the card:
   • Select your timer instance
   • Customize timer buttons
   • Add a custom card title (optional)
   • Enable Show Schedule Panel to let users schedule a future start (off by default)

🔄 Renaming Timer Instances

✅ Recommended Method

1. Go to Settings → Devices & Services
2. Find your Simple Timer integration
3. Click Configure (⚙️ gear icon)
4. Change the name and save

💡 Note on 3-Dots Rename

If you use the 3-dots menu to rename, open Configure once afterward to sync the change.

⏱️ Schedule Timer

Enable Show Schedule Panel in the card editor to add a collapsible "Schedule Timer" panel:

• Pick a start time and run-for duration (free input + quick-fill from your preset buttons).
• One-shot (next occurrence) or Repeat on selected days of the week.
• Once set, the card shows a banner ("Starts … · runs …"); ✕ cancels it.
• Survives Home Assistant restarts. On a reverse-mode card, the schedule runs as a normal bounded timer (start at the time, auto-off after the duration).

Disabled by default - existing cards are unchanged until you turn it on.

📜 History & Activity

Each timer instance exposes a Status sensor (sensor.<name>_status_<id>) alongside the runtime sensor. Its state is one of idle, active, delayed_start, or scheduled.

This is what makes the timer show up in Home Assistant's logbook and in the Activity feed on the device page. The runtime sensor cannot do that job: it reports a number of seconds, and the logbook deliberately skips numeric sensors so it isn't flooded with readings.

Entries read naturally and name whoever triggered them:

9:08 PM   Water Heater   started for 30 minutes by Alex
9:05 PM   Water Heater   finished - device turned off, daily usage 45 minutes
6:00 AM   Water Heater   scheduled for 18:00 (30 minutes), repeating by Alex

Actions the integration takes on its own - a timer expiring, a schedule firing - are intentionally left unattributed rather than credited to the person who set them up hours earlier.

Opening history from the card

Press and hold the countdown display (or the progress bar) for about a second. This opens the status entity's more-info dialog, showing its state timeline and logbook.

There is no icon for this - it's a hidden gesture, so it's worth knowing it exists. It works in every countdown display mode, since the hold is bound to the countdown text and the progress bar alike.

🎛️ Card Configuration

Visual Configuration (Recommended)

Use the card editor in the Home Assistant UI for easy configuration.

Full Configuration Reference

Copy this block to your dashboard configuration and uncomment/edit the lines you need.

type: custom:timer-card
# -------------------------------------------------------------------------
# REQUIRED: Link to your timer instance
# -------------------------------------------------------------------------
timer_instance_id: your_timer_entry_id  # Select the integration entry ID

# -------------------------------------------------------------------------
# TIMER SETTINGS
# -------------------------------------------------------------------------
# Presets: Use numbers (minutes) or strings with units ("30s", "1h", "1d").
timer_buttons:
  - 15
  - 30
  - 45
  - 1h
  - 2d

# reverse_mode will always take priority if both are set to true.
reverse_mode: false           # If true, timer works as "Delayed Start" (turns ON when time ends)
turn_off_on_cancel: true      # Turn off the device when timer is cancelled?

# -------------------------------------------------------------------------
# SLIDER & DISPLAY
# -------------------------------------------------------------------------
card_title: "Water Heater"    # Custom title
hide_slider: false            # Set true to hide the slider
show_daily_usage: true        # Show/Hide the daily usage stats
show_schedule: false          # Show the "Schedule Timer" panel on the card
slider_max: 120               # Maximum value for the slider
slider_unit: min              # Unit for slider: 's', 'min', 'h', 'd'

# -------------------------------------------------------------------------
# STYLING (Optional)
# -------------------------------------------------------------------------
# Icons
entity_state_icon: mdi:lightbulb

# Colors (Hex or RGBA)
slider_thumb_color: "#2ab69c"
slider_background_color: "#424242"
timer_button_font_color: "#ffffff"
timer_button_background_color: "#424242"
power_button_icon_color: "#03a9f4"
power_button_background_color: "#424242"
entity_state_button_icon_color: "#727272"
entity_state_button_background_color: "#1c1c1c"
entity_state_button_icon_color_on: "#03a9f4"
entity_state_button_background_color_on: "#1c1c1c"

Configuration Options

Option	Type	Default	Description
type	string	-	Must be custom:timer-card
timer_instance_id	string	-	Entry ID of your timer instance
timer_buttons	array	[15,30,60,90,120,150]	Timer duration buttons. Supports mixed units (e.g., [30, "15s", "1.5h", "1day"])
card_title	string	-	Custom title for the card
slider_max	integer	120	The maximum value for the slider (supported range: 1–9999)
slider_unit	string	min	Unit for the slider (s, min, h)
reverse_mode	boolean	false	Enable delayed start (turns device ON when timer ends). Note: Disabled if Default Timer is enabled for this entity.
hide_slider	boolean	false	Hide the slider control completely
show_daily_usage	boolean	true	Display daily usage statistics
show_schedule	boolean	false	Show the "Schedule Timer" panel (future-start scheduling)
turn_off_on_cancel	boolean	true	Whether to turn off the entity when the timer is cancelled
slider_thumb_color	string	-	Custom color for the slider thumb (hex or rgba)
slider_background_color	string	-	Custom color for the slider track
timer_button_font_color	string	-	Custom font color for timer buttons
timer_button_background_color	string	-	Custom background color for timer buttons
power_button_background_color	string	-	Custom background color for the power button
power_button_icon_color	string	-	Custom icon color for the power button
entity_state_icon	string	-	Custom icon for the state button (top-left)
entity_state_button_icon_color	string	-	Custom icon color for the entity state button (top-left)
entity_state_button_icon_color_on	string	-	Custom icon color for the entity state button when ON
entity_state_button_background_color	string	-	Custom background color for the entity state button (top-left)
entity_state_button_background_color_on	string	-	Custom background color for the entity state button when ON

❓ Frequently Asked Questions

Can I have multiple timer instances?

Yes! Add multiple integrations for different devices.

Does the timer work if Home Assistant restarts?

Yes, active timers resume automatically with offline time compensation. Scheduled starts also survive restarts (recurring schedules re-arm; a missed one-shot is dropped).

Can I have multiple timer cards?

Yes! You can add multiple cards for the same timer instance on different dashboards (or the same one). They will stay synchronized.

How to trigger a timer with automation?

You can use the simple_timer.start_timer service in your automations or scripts.

triggers:
  - at: "10:00:00"
    trigger: time
actions:
  - data:
      entry_id: your_entry_id # Find this in the entity attributes (e.g.: 01KDQ6WPZDBB3EB89DX407GR6M)
      duration: 30
      unit: s
      reverse_mode: false
    action: simple_timer.start_timer

How to schedule a timer for a future time?

Use the card's Schedule Timer panel, or the simple_timer.schedule_timer service:

action: simple_timer.schedule_timer
data:
  entry_id: your_entry_id      # or entity_id: sensor.your_timer_runtime_...
  start_time: "21:30:00"
  duration: 30
  unit: min
  repeat: true                 # optional; daily/recurring
  days: [mon, tue, wed, thu, fri]   # optional; empty = every day

Cancel an armed schedule with simple_timer.cancel_schedule (same entry_id/entity_id).

Can I control my A/C or Climate entity?

Yes, directly. Select the climate entity when you add the integration instance, and pick the mode it should run in.

What "on" means. A switch is on or off. A climate entity has no "on" - its state is its mode (heat, cool, dry, fan_only, auto, heat_cool, or off). So you choose one mode when you set the timer up, and that is what the timer applies. Turning off is always off.

Any non-off mode counts as running. The device is metered, and the card shows it as on, in every mode. That has three consequences worth knowing:

• Changing the mode during a timer does not cancel it. Start a 2 hour timer in cool, switch the unit to heat by hand, and the timer keeps running - the device is still on, and that is what the timer is counting.
• Turning the device off does cancel it, the same as with a switch.
• A unit that goes unavailable does not cancel it. An entity that stopped answering has not told us it is off, and losing a timer to a dropped Zigbee message would be worse than waiting.

Starting a timer on a unit that is already running leaves its mode alone. The configured mode is applied when the device is off. The one exception is a delayed start: when it fires, it applies the configured mode, because "turn it on at 21:30" has to mean something specific.

Upgrading with a cached card? A browser holding an old card bundle shows a climate timer as off and its power button may not work. Hard-refresh (Ctrl+Shift+R) once.

The old workaround - an input_boolean helper plus an automation - still works and is no longer needed. It is only worth keeping if your automation does more than turn the unit on and off, for example setting a target temperature.

Can I customize the timer buttons?

Yes! You can configure values with explicit units. Example: timer_buttons: [30, "45s", "1.5h", "1d"].

When does the daily usage counter reset?

At the Daily Usage Reset Time configured on the integration instance (Settings → Devices & Services → Simple Timer → Configure). It defaults to 00:00, so usage resets at midnight unless you change it. Pick any time of day if your tracking or billing day starts elsewhere.

If Home Assistant is offline when that time passes, the reset is caught up on the next start, and the card shows a note saying the reset was a catch-up.

Why does my usage show a warning message?

This appears when HA was offline during a timer to indicate potential time sync issues.

🚨 Troubleshooting

Card Not Appearing in Card Picker

1. Restart Home Assistant: The card is installed during integration setup
2. Check integration logs: Look for any errors during the card installation process
3. Verify automatic installation: Check if /config/www/simple-timer/timer-card.js exists
4. Clear browser cache: Hard refresh with Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
5. Check browser console: Press F12 and look for JavaScript errors

Timer Not Working

1. Check device entity: Ensure the controlled device exists and is accessible
2. Verify integration setup: Go to Settings → Devices & Services → Simple Timer
3. Check logs: Look for errors in Settings → System → Logs
4. Restart integration: Remove and re-add the integration if needed

Daily Usage Not Tracking

1. Device state changes: Timer only tracks when the device is actually ON
2. Manual control: If you turn the device off manually, tracking stops (by design)
3. Daily reset: Usage resets once a day at the configured reset time (00:00 by default)

Card Installation Issues

If the automatic card installation fails:

1. Check file permissions: Ensure Home Assistant can write to the www directory
2. Verify disk space: Ensure sufficient space for file copying
3. Check integration logs: Look for specific error messages
4. Manual fallback: You can still manually copy the card file from the integration's dist folder

Card Not Updating After Upgrade

If you don't see new features (like the Default Timer option) after updating:

1. Clear browser cache: Hard refresh with Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
2. Reload Resources: Call the simple_timer.reload_resources service from Developer Tools → Services to force the frontend to load the latest version.

📝 Getting Help

If you encounter issues:

1. Check the Issues page for existing solutions
2. Enable debug logging:

   logger:
     logs:
       custom_components.simple_timer: debug

3. Create a new issue with:
   • Home Assistant version
   • Integration version
   • Detailed error description
   • Relevant log entries

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⭐ Support

If you find this integration useful, please consider:

• ⭐ Starring this repository
• 🐛 Reporting bugs you encounter
• 💡 Suggesting new features
• 📖 Improving documentation

---

Star History

Made with ❤️ for the Home Assistant community