Complete Pi-hole monitoring and control for Home Assistant
Built with the tools and technologies:
A comprehensive dashboard card for managing and monitoring your Pi-hole DNS ad blocker directly from Home Assistant. The card provides real-time statistics and controls in an intuitive, dashboard-style interface that matches the Pi-hole visual identity.
- Main Statistics Dashboard - Four color-coded tiles showing your most important Pi-hole metrics:
- Total DNS Queries
- Queries Blocked
- Block Percentage
- Domains on Blocklists
- Client Statistics - See active clients, unique domains, unique clients, etc.
- Performance Data - View cached queries and forwarded DNS requests
- Interactive Elements - Configurable tap, hold, and double-tap actions for all metrics
- Enable/Disable Controls - Toggle Pi-hole filtering with a single click as well as Group Default
- Pause Ad-Blocking - Temporarily disable filtering for a specified duration:
- Configurable durations (default: 60s, 5min, 15min)
- Automatically re-enables filtering after time expires
- Shows remaining time until blocking resumes
- Pause multiple Pi-holes if configured
- Action Buttons - Quick access buttons for common maintenance tasks:
- Restart DNS
- Update Gravity
- Flush ARP
- Flush Logs
- Customizable Actions - Configure custom actions for the control buttons in this section
- Component Versions - Display installed versions for all Pi-hole components:
- Core
- Docker
- FTL
- Web Interface
- Home Assistant Integration
- Last Refresh Time
- Real-time Status - Visual indication of Pi-hole's current state
- Error Detection - Automatic highlighting when issues are detected
- Update Indicators - Clear notification when updates are available
- Block Time Remaining - Shows remaining time until ad-blocking resumes when paused
- FTL Diagnostic Message Count - Shows diagnostic message count when more than 0
- Clickable Elements - All sections can be configured with custom actions
- Visual Indicators - Color-coded statistics to understand status at a glance
- Customizable Card - Set custom title and icon to match your dashboard style
- Entity Filtering - Ability to exclude specific entities or entire sections
- Collapsible Sections - Ability to collapse/expand sections to save space:
- Switches section (on/off toggles)
- Actions section (control buttons)
- Pause section (pause durations)
- Centralized Control - Manage multiple Pi-hole instances from a single card
- Aggregated Status - See at a glance how many of your Pi-holes are active
- Unified Control - Centralized access to all switches from your Pi-hole instances
- Intelligent Status Indicators - Status automatically adjusts based on collective state:
- Shows "Running" when all instances are active
- Shows "Partial" when some instances are active and some are inactive
- Shows count of active instances (e.g., "2/3")
Example of Partial
Example of all Running
Note
The multi-Pi-hole feature currently has some limitations:
- Statistics shown are from the first Pi-hole in the list only
- All switches from all Pi-holes are displayed in a single list
- Only header status reflects the multi-Pi-hole state
- Mobile-friendly - Optimized layout for both desktop and mobile viewing
- Fluid Layout - Responsive design adapts to available space
Warning
Before using this card, please ensure you have the Pi-hole v6 integration installed in your Home Assistant instance.
- Open HACS in your Home Assistant instance
- Click the menu icon in the top right and select "Custom repositories"
- Add this repository URL and select "Dashboard" as the category
https://github.com/homeassistant-extras/pi-hole-card
- Click "Install"
- Download the
pi-hole-card.jsfile from the latest release in the Releases tab. - Copy it to your
www/community/pi-hole-card/folder - Add the following to your
configuration.yaml(or add as a resource in dashboards menu)
lovelace:
resources:
- url: /local/community/pi-hole-card/pi-hole-card.js
type: moduleAdd the card to your dashboard using the UI editor or YAML:
The card is fully configurable through the card editor, allowing you to customize:
- Pi-hole device selection (single or multiple)
- Card title and icon
- Custom actions for statistics, info panels, and control buttons
This is the most minimal configuration needed to get started:
type: custom:pi-hole
device_id: your_pihole_device_idFor multiple Pi-hole instances:
type: custom:pi-hole
device_id:
- your_first_pihole_device_id
- your_second_pihole_device_id
- etc..The card will automatically:
- Detect all Pi-hole entities associated with the device(s)
- Organize statistics in the dashboard layout
- Display control buttons for common actions
- Show version information for all components
- For multiple Pi-holes: combine switches and show aggregated status
If you're unsure what your Pi-hole device ID is, here are several ways to find it:
- Add the card through the visual editor
- Select your Pi-hole device from the dropdown
- Click "Show Code Editor" or "View YAML" to see the generated configuration
- Copy the
device_idvalue for use in manual YAML configuration
- Go to Settings → Devices & Services → Devices
- Search for "Pi-hole" or browse to find your Pi-hole device
- Click on the device and look at the URL - the device ID will be in the URL path
| Name | Type | Default | Description |
|---|---|---|---|
| device_id | string or array | Required | The ID(s) of your Pi-hole device(s) in Home Assistant |
| title | string | Pi-Hole | Custom title for the card header |
| icon | string | mdi:pi-hole | Custom icon for the card header |
| pause_durations | array | [60,300,900] | Durations in seconds for the pause buttons |
| stats | object | none | Configure actions for statistics tiles |
| info | object | none | Configure actions for additional info items |
| controls | object | none | Configure actions for control buttons |
| exclude_sections | list | none | Sections of entities to exclude. See below. |
| exclude_entities | list | none | Entities to remove from the card. |
| entity_order | list | none | Custom order for switch, button, sensor entities or dividers. |
| collapsed_sections | list | none | Sections to be initially collapsed. See below. |
| switch_spacing | string | flex | Layout style for switches: flex, space-around, space-between |
Each section (stats, info, controls) supports the following action types:
| Name | Type | Default | Description |
|---|---|---|---|
| tap_action | object | optional | Action to perform when tapped |
| hold_action | object | optional | Action to perform when held |
| double_tap_action | object | optional | Action to perform when double-tapped |
Actions can be configured to perform various operations such as:
- Toggle entities
- Show more info
- Call services
- Navigate to different views
- And more!
The following section names can be used with exclude_sections:
- actions
- footer
- header
- pause
- statistics
- sensors
- switches
The following section names can be used with collapsed_sections:
- actions
- switches
- pause
The switch_spacing option controls how switches are arranged in the switches section:
- flex (default): Switches flow naturally with standard flexbox behavior
- space-around: Equal space around each switch
- space-between: Maximum space between switches, no space at edges
The card automatically discovers and identifies all Pi-hole entities based on:
- Entity naming patterns
- Translation keys
- Entity relationships to the device
This includes sensors, buttons, switches, binary sensors, and update entities.
type: custom:pi-hole
device_id: pi_hole_device_1type: custom:pi-hole
device_id:
- pi_hole_device_1
- pi_hole_device_2
title: 'My Pi-hole Network'type: custom:pi-hole
device_id: pi_hole_device_1
title: 'My Pi-hole Server'
icon: 'mdi:shield-check'type: custom:pi-hole
device_id: pi_hole_device_1
pause_durations:
- 60 # 1 minute
- 300 # 5 minutes
- 1800 # 30 minutes
- 3600 # 1 hourtype: custom:pi-hole
device_id: pi_hole_device_1
exclude_sections:
- sensors
- switches
exclude_entities:
- button.pi_hole_action_refresh_data
- sensor.pi_hole_latest_data_refreshtype: custom:pi-hole
device_id: pi_hole_device_1
title: 'Network Protection'
stats:
tap_action:
action: more-info
hold_action:
action: navigate
navigation_path: /lovelace/network
controls:
tap_action:
action: toggle
hold_action:
action: more-infotype: custom:pi-hole
device_id: pi_hole_device_1
# Configure stat box actions
stats:
tap_action:
action: call-service
perform_action: browser_mod.popup
data:
title: Pi-hole Statistics
content: 'Detailed view of Pi-hole stats'
hold_action:
action: navigate
navigation_path: /lovelace/network-monitoring
# Configure additional info actions
info:
tap_action:
action: more-info
double_tap_action:
action: toggle
# Configure control button actions
controls:
tap_action:
action: toggle
hold_action:
action: more-info
double_tap_action:
action: call-service
perform_action: browser_mod.popup
data:
title: Pi-hole Controls
content: 'Advanced Pi-hole control panel'type: custom:pi-hole
device_id: pi_hole_device_1
switch_spacing: 'space-around'
entity_order:
- button.pi_hole_action_refresh_data
- sensor.pi_hole_dns_queries_today
- sensor.pi_hole_ads_blocked_today
- switch.pi_holetype: custom:pi-hole
device_id: pi_hole_device_1
entity_order:
- button.pi_hole_action_refresh_data
- divider
- sensor.pi_hole_dns_queries_today
- sensor.pi_hole_ads_blocked_today
- divider
- switch.pi_hole
type: custom:pi-hole
device_id: pi_hole_device_1
collapsed_sections:
- actions
- switches
- pause # Start with pause section collapsed-
Initial design: create initial card design -
Auto-discovery: automatic detection of Pi-hole entities -
Dashboard statistics: visual representation of key metrics -
Control buttons: quick actions for common Pi-hole tasks -
Version info: display component versions -
Custom actions: tap/hold/double-tap actions for all elements - thanks @dunxd -
Card customization: custom title and icon options -
Performance optimizations: improved code structure and efficiency -
Enhanced entity mapping: better entity identification with translation keys - thanks @bastgau -
Translations: ability to add translations - thanks @ajavibp -
Multi-Pi-hole support: manage and monitor multiple Pi-hole instances - thanks @Drudoo -
Collapsible sections: collapse/expand card sections to save space - thanks @Teleportist -
Additional visualization options: using HA native more-info, etc. - thanks @dunxd -
Pause ad-blocking: temporarily disable filtering for specified durations - thanks @StuartHaire, @VVRud -
Entity ordering: customize the order of displayed entities - thanks @Teleportist -
Section hiding: ability to disable sections or entities - thanks @pcnate, @bastgau, @Anto79-ops -
Visual separators: add dividers for switches - thanks @Teleportist -
Diagnostics info indicator: show diagnostic messages count - thanks @WalterPepeka -
Links directly to sub pages: direct links to specific Pi-hole admin pages
- 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
- 🐛 Report Issues: Submit bugs found or log feature requests for the
pi-holeproject. - 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.
- 📣 Check out discord: Need further help, have ideas, want to chat?
- 🃏 Check out my other cards! Maybe you have an integration that I made cards for.
Contributing Guidelines
- Fork the Repository: Start by forking the project repository to your GitHub account.
- Clone Locally: Clone the forked repository to your local machine using a git client.
git clone https://github.com/homeassistant-extras/pi-hole-card
- Create a New Branch: Always work on a new branch, giving it a descriptive name.
git checkout -b new-feature-x
- Make Your Changes: Develop and test your changes locally.
- Commit Your Changes: Commit with a clear message describing your updates.
git commit -m 'Implemented new feature x.' - Push to GitHub: Push the changes to your forked repository.
git push origin new-feature-x
- Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
- Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!
The Pi-hole card supports multiple languages to provide a better experience for users worldwide.
- English
- Spanish
Want to contribute a translation? See our translation guide for instructions.
This project is protected under the MIT License. For more details, refer to the LICENSE file.
- Built using LitElement
- Inspired by Pi-hole's own dashboard design
- Thanks to all contributors!
Forgive me and my badges..
Stats
Ratings