0.28.0 - Custom pause actions, aggregation modes and new shiny documentation 🐌🏑

Documentation: User guides and the full configuration reference live at homeassistant-extras.github.io/pi-hole-card now! You can search, browse, and bookmark more easily.

Breaking change (with a long grace period)

Pause configuration now belongs under a single pause key: use pause.durations for the timer buttons (instead of a root-level pause_durations list).

Root-level pause_durations still works today so existing dashboards keep running. It will be removed in a long while, migrate when you next edit the card; there is no urgent deadline.

"The only way to make sense out of change is to plunge into it, move with it, and join the dance." - Alan Watts

Full migration notes and duration formats are in Pause configuration (the pause key).

New: custom pause button actions with context

You can set pause.tap_action like other card sections (badge, stats, etc.). Each pause duration button then runs that dashboard action, for example perform-action / call-service to a script or another integration, instead of the built-in Pi-hole disable call. Omit pause.tap_action to keep the default Pi-hole behavior.

String values inside pause.tap_action can include card-local placeholders (not Home Assistant Jinja). They are replaced with the clicked duration and card context before the action runs:

Placeholder	Meaning
{{ pause_seconds }}	Seconds for the button that was tapped
{{ pause_minutes }}	That duration in minutes (may be fractional)
{{ device_id }}	Card device_id (first id if a list)
{{ entity_id }}	Selected switch when group pausing is on

See Custom pause button action in Pause configuration for behavior details (e.g. numeric vs string substitution).

Examples

Call a script when a pause button is tapped:

type: custom:pi-hole
device_id: pi_hole_device_1
pause:
  durations:
    - 60
    - 300
  tap_action:
    action: perform-action
    perform_action: script.pause_pi_and_announce_on_speakers
    data:
      seconds: '{{ pause_seconds }}'
      entity_id: '{{ entity_id }}'

Pass minutes and device id into service data:

pause:
  tap_action:
    action: perform-action
    perform_action: controld_manager.disable_profile
    data:
      minutes: '{{ pause_minutes }}'
      profile_id:
        - '{{ device_id }}'

🪞 Multi-Pi-hole aggregation modes

If you run more than one Pi-hole you can now tell the card how to combine the four main tiles

type: custom:pi-hole
device_id:
  - pi_hole_1
  - pi_hole_2
  - pi_hole_3
aggregation:
  mode: mirrored

Two modes to start with:

• load_balanced (default) — same behavior you have today. Total Queries, Queries Blocked, Domains on Lists and Active Clients all sum across instances, and % Blocked is weighted by real query volume. Existing dashboards keep working with zero changes.
• mirrored — every tile behaves the same as load_balanced except Domains on Lists, which shows the integer average across instances. Use this when your Pi-holes share identical blocklists and you do not want a 3-node setup to report 3× the real list size. Active clients still sums because, even with multiple Pi-holes configured, clients commonly resolve through only one at a time (the others act as failover).

Full details and example configurations are in the aggregation docs and the updated multi Pi-hole guide.

---

• chore: bumps version to 0.28.0 by @gh-action-bump-version
• aggragation modes - thanks @mtwhitley! by @warmfire540
• documentation refactored to gh pages by @warmfire540
• pause action configurable - thanks @ccpk1! by @warmfire540
• chore: yarn (deps-dev): bump the all-dependencies group with 3 updates (#134) by @dependabot[bot]
• chore: yarn (deps-dev): bump @types/sinon in the all-dependencies group (#132) by @dependabot[bot]

What's Changed

• Custom pause actions, aggregation modes and new shiny documentation 🐌🏑 by @warmfire540 in #135

Full Changelog: 0.27.1...0.28.0

Pause Tap Actions

• pause action configurable - thanks @ccpk1! by @warmfire540
• chore: yarn (deps-dev): bump the all-dependencies group with 3 updates (#134) by @dependabot[bot]
• chore: yarn (deps-dev): bump @types/sinon in the all-dependencies group (#132) by @dependabot[bot]

What's Changed

• chore: yarn (deps-dev): bump @types/sinon from 21.0.0 to 21.0.1 in the all-dependencies group by @dependabot[bot] in #132
• chore: yarn (deps-dev): bump the all-dependencies group with 3 updates by @dependabot[bot] in #134

Full Changelog: 0.27.0...0.27.1

0.27.0 - Stat box number format respected 🌍🔢

🌍 Stat box number format

Large dashboard stat boxes now respect your Home Assistant profile Number format setting.

---

• chore: bumps version to 0.27.0 by @gh-action-bump-version
• number locale - thanks @Lavve! by @warmfire540
• chore: yarn (deps-dev): bump typescript from 5.9.3 to 6.0.2 (#127) by @dependabot[bot]
• chore: yarn (deps): bump lodash-es from 4.17.23 to 4.18.1 (#130) by @dependabot[bot]
• chore: yarn (deps): bump picomatch from 2.3.1 to 2.3.2 (#129) by @dependabot[bot]
• chore: yarn (deps-dev): bump @types/jsdom in the all-dependencies group (#128) by @dependabot[bot]
• chore: yarn (deps-dev): bump jsdom in the all-dependencies group (#126) by @dependabot[bot]
• chore: yarn (deps-dev): bump jsdom from 28.1.0 to 29.0.0 (#125) by @dependabot[bot]
• chore: yarn (deps-dev): bump sinon in the all-dependencies group (#124) by @dependabot[bot]
• chore: yarn (deps): bump undici from 7.22.0 to 7.24.1 (#123) by @dependabot[bot]
• chore: yarn (deps-dev): bump sinon in the all-dependencies group (#122) by @dependabot[bot]

What's Changed

• chore: yarn (deps-dev): bump sinon from 21.0.1 to 21.0.2 in the all-dependencies group by @dependabot[bot] in #122
• chore: yarn (deps): bump undici from 7.22.0 to 7.24.1 by @dependabot[bot] in #123
• chore: yarn (deps-dev): bump sinon from 21.0.2 to 21.0.3 in the all-dependencies group by @dependabot[bot] in #124
• chore: yarn (deps-dev): bump jsdom from 28.1.0 to 29.0.0 by @dependabot[bot] in #125
• chore: yarn (deps-dev): bump jsdom from 29.0.0 to 29.0.1 in the all-dependencies group by @dependabot[bot] in #126
• chore: yarn (deps-dev): bump @types/jsdom from 28.0.0 to 28.0.1 in the all-dependencies group by @dependabot[bot] in #128
• chore: yarn (deps): bump picomatch from 2.3.1 to 2.3.2 by @dependabot[bot] in #129
• chore: yarn (deps): bump lodash-es from 4.17.23 to 4.18.1 by @dependabot[bot] in #130
• chore: yarn (deps-dev): bump typescript from 5.9.3 to 6.0.2 by @dependabot[bot] in #127
• Stat box number format respected 🌍🔢 by @warmfire540 in #131

Full Changelog: 0.26.0...0.27.0

0.26.0 - Pause Dropdown Fix for HA 2026.3+ 🎉✨

Pause Group Selector Fixed

Fixed the pause ad-blocking group selector dropdown that was broken in Home Assistant 2026.3.1. The dropdown now correctly shows all Pi-hole instances and client groups when selecting which to pause, instead of only displaying the raw entity ID.

Note: This fix requires Home Assistant 2026.3 or later. Probably the dropdown will not work in later versions of HA...

---

• chore: bumps version to 0.26.0 by @gh-action-bump-version
• code smells by @warmfire540
• ha-select fix for 2026.3.1 - thanks @trxraptor! by @warmfire540
• chore: yarn (deps-dev): bump @types/jsdom from 27.0.0 to 28.0.0 (#118) by @dependabot[bot]
• chore: yarn (deps-dev): bump nyc from 17.1.0 to 18.0.0 (#119) by @dependabot[bot]
• chore: yarn (deps-dev): bump jsdom in the all-dependencies group (#117) by @dependabot[bot]
• chore: yarn (deps-dev): bump jsdom from 27.4.0 to 28.0.0 (#114) by @dependabot[bot]
• chore: yarn (deps): bump qs from 6.14.1 to 6.14.2 (#116) by @dependabot[bot]
• chore: yarn (deps-dev): bump the all-dependencies group with 2 updates (#113) by @dependabot[bot]

What's Changed

• Pause Dropdown Fix for HA 2026.3+ 🎉✨ by @warmfire540 in #121

Full Changelog: 0.25.0...0.26.0

0.25.0 - Combined Statistics for Multi-Pi-hole Setups + Version Update Info 🚦 🥼

Thanks for the support, everyone!! Star the GH repo if you haven't had a chance to yet!

New Feature: Aggregated Dashboard Statistics

When using multiple Pi-hole instances, the four main dashboard statistics are now automatically combined across all instances:

• Total DNS Queries - Sum of all queries from all Pi-hole instances
• Queries Blocked - Sum of all blocked queries from all instances
• Block Percentage - Recalculated from combined totals: (total blocked / total queries) × 100
  • This accounts for query volume differences between instances, providing an accurate overall percentage
• Domains on Blocklists - Sum of domains blocked across all instances

One Pi vs Multi-Pi card:

The statistics are intelligently aggregated:

• Numeric values (queries, blocked, domains) are summed across all instances
• Percentage is recalculated from the combined totals to ensure accuracy regardless of query volume differences
• Active clients count is also summed across all instances

This provides a true aggregate view of your entire Pi-hole network's performance in a single card.

New Feature: Update Available Highlighting

Version information items now visually highlight when updates are available:

• Visual Indicator - Items with available updates display a colored left border to draw attention
• Latest Version Display - When an update is available, the latest version is shown alongside the installed version (e.g., "v1.2.3 → v1.2.4")
• Automatic Detection - Uses Home Assistant's update entity state to automatically detect when updates are available
• Clear Formatting - Latest version is displayed in a warning color with clear separation from the installed version

This makes it easy to see at a glance which Pi-hole components have updates available.

Refactoring

• Extracted chart processing logic from SystemMetricsGraph into standalone utility functions with comprehensive test coverage

---

• chore: bumps version to 0.25.0 by @gh-action-bump-version
• code smells by @warmfire540
• highlight if update available - thanks @IIIdefconIII! by @warmfire540
• refactor chart logic for testing by @warmfire540
• main 4 statistics boxes combine multi pi results - thanks @heylers by @warmfire540
• chore: yarn (deps-dev): bump prettier in the all-dependencies group (#110) by @dependabot[bot]
• chore: yarn (deps): bump lodash-es from 4.17.21 to 4.17.23 (#109) by @dependabot[bot]
• chore: yarn (deps-dev): bump prettier in the all-dependencies group (#108) by @dependabot[bot]
• chore: yarn (deps-dev): bump @trivago/prettier-plugin-sort-imports (#106) by @dependabot[bot]
• chore: yarn (deps-dev): bump @trivago/prettier-plugin-sort-imports (#104) by @dependabot[bot]
• chore: yarn (deps): bump qs from 6.14.0 to 6.14.1 (#101) by @dependabot[bot]
• chore: yarn (deps): bump the all-dependencies group with 3 updates (#100) by @dependabot[bot]
• chore: yarn (deps-dev): bump sinon in the all-dependencies group (#99) by @dependabot[bot]

What's Changed

• chore: yarn (deps-dev): bump sinon from 21.0.0 to 21.0.1 in the all-dependencies group by @dependabot[bot] in #99
• chore: yarn (deps): bump the all-dependencies group with 3 updates by @dependabot[bot] in #100
• chore: yarn (deps): bump qs from 6.14.0 to 6.14.1 by @dependabot[bot] in #101
• chore: yarn (deps-dev): bump @trivago/prettier-plugin-sort-imports from 6.0.0 to 6.0.1 in the all-dependencies group by @dependabot[bot] in #104
• chore: yarn (deps-dev): bump @trivago/prettier-plugin-sort-imports from 6.0.1 to 6.0.2 in the all-dependencies group by @dependabot[bot] in #106
• chore: yarn (deps-dev): bump prettier from 3.7.4 to 3.8.0 in the all-dependencies group by @dependabot[bot] in #108
• chore: yarn (deps): bump lodash-es from 4.17.21 to 4.17.23 by @dependabot[bot] in #109
• chore: yarn (deps-dev): bump prettier from 3.8.0 to 3.8.1 in the all-dependencies group by @dependabot[bot] in #110
• Combined Statistics for Multi-Pi-hole Setups + Version Update Info 🚦 🥼 by @warmfire540 in #112

Full Changelog: 0.24.0...0.25.0

0.24.0 - Editor supports multi pi setup

Features

• Multiple device selection in editor: The editor now supports selecting multiple Pi-hole devices. When a single device is selected, it's saved as a string (backwards compatible). When multiple devices are selected, they're saved as an array. Existing configurations with a single device continue to work without changes.

---

• chore: bumps version to 0.24.0 by @gh-action-bump-version
• editor supports multi pi setup by @warmfire540

What's Changed

• Editor supports multi pi setup by @warmfire540 in #98

Full Changelog: 0.23.0...0.24.0

0.23.0 - Editor no longer deletes action configuration ✂️ 🦩

Bug Fixes

• Fixed editor deleting interaction configurations: Fixed an issue where interaction configurations (badge, stats, info, controls) were being deleted when reopening the editor. The cleanup logic now only removes sections when all actions are empty, preserving sections that have at least one action configured.

---

• chore: bumps version to 0.23.0 by @gh-action-bump-version
• editor doesn't delete actions by @warmfire540

What's Changed

• Editor no longer deletes action configuration ✂️ 🦩 by @warmfire540 in #96

Full Changelog: 0.22.0...0.23.0

0.22.0 - Systems metrics chart entities are identified correctly 📊 🦘

System Metrics Chart

• Improved sensor identification: CPU and memory sensors are now identified using translation keys (cpu_use and memory_use) instead of entity IDs
• This makes the system metrics chart more robust and continues to work correctly even if users rename their sensor entities
• CPU and memory sensors are now first-class properties on the device object for better code organization

---

• chore: bumps version to 0.22.0 by @gh-action-bump-version
• identify graph entities by translation_key by @warmfire540
• chore: yarn (deps-dev): bump the all-dependencies group with 4 updates (#93) by @dependabot[bot]

What's Changed

• chore: yarn (deps-dev): bump the all-dependencies group with 4 updates by @dependabot[bot] in #93
• Systems metrics chart entities are identified correctly 📊 🦘 by @warmfire540 in #94

Full Changelog: 0.21.0...0.22.0

0.21.0 - Flag added so pausing works in HAS version of integration! ⏸️ 🧷

New Feature: Home Assistant Integration Support

Added ha_integration Feature Flag

Added support for using the built-in Home Assistant Pi-hole integration (pi_hole domain) instead of the Pi-hole v6 integration (pi_hole_v6 domain) for pause operations.

What's New:

• New ha_integration feature flag allows the card to work with the built-in Home Assistant Pi-hole integration
• When enabled, pause operations use the pi_hole domain instead of pi_hole_v6
• Fully configurable through the card editor or YAML configuration

Usage:

Enable the feature flag in your card configuration:

type: custom:pi-hole
device_id: your_pihole_device_id
features:
  - ha_integration
  - disable_group_pausing # may not be supported in HAS version

When to Use:

• If you're using the built-in Home Assistant Pi-hole integration instead of the Pi-hole v6 integration
• When you want to use the pi_hole domain for pause service calls

---

• chore: bumps version to 0.21.0 by @gh-action-bump-version
• documentation updates by @warmfire540
• pause works in has version - thanks @ejpenney! by @warmfire540
• chore: yarn (deps-dev): bump prettier in the all-dependencies group (#89) by @dependabot[bot]
• chore: yarn (deps-dev): bump @types/sinon from 17.0.4 to 21.0.0 (#88) by @dependabot[bot]
• chore: yarn (deps-dev): bump the all-dependencies group with 2 updates (#87) by @dependabot[bot]
• chore: yarn (deps-dev): bump @trivago/prettier-plugin-sort-imports (#85) by @dependabot[bot]
• chore: yarn (deps-dev): bump the all-dependencies group with 3 updates (#84) by @dependabot[bot]
• missing translations for chart features by @warmfire540

What's Changed

• chore: yarn (deps-dev): bump the all-dependencies group with 3 updates by @dependabot[bot] in #84
• chore: yarn (deps-dev): bump @trivago/prettier-plugin-sort-imports from 5.2.2 to 6.0.0 by @dependabot[bot] in #85
• chore: yarn (deps-dev): bump the all-dependencies group with 2 updates by @dependabot[bot] in #87
• chore: yarn (deps-dev): bump @types/sinon from 17.0.4 to 21.0.0 by @dependabot[bot] in #88
• chore: yarn (deps-dev): bump prettier from 3.6.2 to 3.7.3 in the all-dependencies group by @dependabot[bot] in #89
• Flag added so pausing works in HAS version of integration! ⏸️ 🧷 by @warmfire540 in #91

Full Changelog: 0.20.0...0.21.0

0.20.0 - System Metrics Chart for mem & cpu usage 📈 🧭

System Metrics Chart Feature

Overview

The Pi-hole Card now includes a new System Metrics Chart feature that displays real-time CPU and memory usage for your Pi-hole instance.

Features

CPU and Memory Usage Visualization

• 24-Hour Historical Data: View your Pi-hole's system resource usage over the last 24 hours
• Dual Metrics: Track both CPU usage and memory consumption in a single chart
• Automatic Data Fetching: Chart automatically retrieves statistics data from Home Assistant's recorder
• Real-time Updates: Chart updates automatically when data changes

Customizable Appearance

The chart supports multiple line style options to match your dashboard aesthetic:

• Normal (default): Standard solid lines with filled areas beneath
• Gradient: Beautiful gradient-colored lines with gradient-filled areas
• Gradient No Fill: Gradient lines without fill areas for a cleaner look
• No Fill: Solid lines without fill areas

Configuration Options

Exclude Chart Section:

exclude_sections:
  - chart

Customize Chart Line Style:

chart:
  line_type: gradient  # Options: normal, gradient, gradient_no_fill, no_fill

Requirements

• Home Assistant with the Recorder component enabled
• Pi-hole sensors for CPU and memory usage (sensor.pi_hole_cpu_use and sensor.pi_hole_memory_use)
• Statistics data must be available in Home Assistant's recorder

Technical Details

• Chart uses Chart.js for rendering
• Data is fetched from Home Assistant's recorder/statistics_during_period WebSocket API
• Chart displays 5-minute interval data points
• Responsive design adapts to card width
• Automatically handles missing or empty data gracefully

Benefits

• Performance Monitoring: Easily identify resource usage patterns and potential performance issues
• Visual Insights: Quickly spot CPU or memory spikes that might indicate problems
• Historical Context: Understand how your Pi-hole's resource usage changes over time
• Dashboard Integration: Seamlessly integrated into the existing Pi-hole Card layout

Backwards Compatibility Improvements

Entity Mapping Updates

• Added backwards compatibility mapping for ads_percentage_today entity translation key to map to ads_percentage_blocked_today

---

• chore: bumps version to 0.20.0 by @gh-action-bump-version
• ads_percentage_today key mapped for HA edge case by @warmfire540
• mem & cpu chart added to card bottom by @warmfire540
• chore: yarn (deps-dev): bump jsdom in the all-dependencies group (#78) by @dependabot[bot]
• chore: yarn (deps-dev): bump @types/chai in the all-dependencies group (#76) by @dependabot[bot]

What's Changed

• chore: yarn (deps-dev): bump @types/chai from 5.2.2 to 5.2.3 in the all-dependencies group by @dependabot[bot] in #76
• chore: yarn (deps-dev): bump jsdom from 27.0.1 to 27.1.0 in the all-dependencies group by @dependabot[bot] in #78
• System Metrics Chart for mem & cpu usage 📈 🧭 by @warmfire540 in #82

Full Changelog: 0.19.0...0.20.0