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, or fan

⚡ 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

🌙 Midnight Reset - Daily usage statistics reset automatically at midnight

👆 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
• 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)
5. Give your timer instance a descriptive name (e.g., "Kitchen Timer", "Water Heater")
6. Choose notification entitiy (optional) - can be add more than one
7. Check show seconds (optional) - display seconds in uasge time and notifications

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.

🎛️ 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?

Not directly, but you can achieve this easily!

1. Create a Helper (Input Boolean) for your timer (e.g., input_boolean.ac_timer).
2. Point the Simple Timer integration to this helper.
3. Create an automation that acts on the helper's state changes:

alias: "A/C Timer Control"
trigger:
  - platform: state
    entity_id: input_boolean.ac_timer
    to: "on"
    id: "start"
  - platform: state
    entity_id: input_boolean.ac_timer
    to: "off"
    id: "stop"
action:
  - choose:
      - conditions:
          - condition: trigger
            id: "start"
        sequence:
          - service: climate.turn_on
            target:
              entity_id: climate.living_room_ac
      - conditions:
          - condition: trigger
            id: "stop"
        sequence:
          - service: climate.turn_off
            target:
              entity_id: climate.living_room_ac

Can I customize the timer buttons?

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

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. Midnight reset: Usage resets at 00:00 each day automatically

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