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, and time remaining
- 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
- Action Buttons - Quick access buttons for common maintenance tasks:
- Refresh Data
- 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
- 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
- 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
- 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.jsfile from the latest release in the Releases tab. - Copy it to your
www/community/pi-hole/folder - Add the following to your
configuration.yaml(or add as a resource in dashboards menu)
lovelace:
resources:
- url: /local/community/pi-hole/pi-hole.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
- 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_idThe card will automatically:
- Detect all Pi-hole entities associated with the device
- Organize statistics in the dashboard layout
- Display control buttons for common actions
- Show version information for all components
| Name | Type | Default | Description |
|---|---|---|---|
| device_id | string | Required | The ID of your Pi-hole device in Home Assistant |
| title | string | Pi-Hole | Custom title for the card header |
| icon | string | mdi:pi-hole | Custom icon for the card header |
| stats | object | optional | Configure actions for statistics tiles |
| info | object | optional | Configure actions for additional info items |
| controls | object | optional | Configure actions for control buttons |
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 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
title: 'My Pi-hole Server'
icon: 'mdi:shield-check'type: 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'-
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 -
Card customization: custom title and icon options -
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!
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!
Stats
Ratings