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