https://github.com/homeassistant-extras/pi-hole-card
Card to summarize information for, and to control your Pi-Hole 6 instance!
https://github.com/homeassistant-extras/pi-hole-card
hacs hacs-integration home-assistant home-assistant-addons home-assistant-custom home-assistant-frontend home-assistant-integration pi-hole
Last synced: about 1 month ago
JSON representation
Card to summarize information for, and to control your Pi-Hole 6 instance!
- Host: GitHub
- URL: https://github.com/homeassistant-extras/pi-hole-card
- Owner: homeassistant-extras
- License: mit
- Created: 2025-05-04T18:23:43.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-05-05T23:49:44.000Z (about 1 month ago)
- Last Synced: 2025-05-06T00:35:40.513Z (about 1 month ago)
- Topics: hacs, hacs-integration, home-assistant, home-assistant-addons, home-assistant-custom, home-assistant-frontend, home-assistant-integration, pi-hole
- Language: TypeScript
- Homepage:
- Size: 15.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Pi-hole Card
Pi-hole Card
Complete Pi-hole monitoring and control for Home Assistant
[](https://github.com/hacs/integration)
Built with the tools and technologies:
## Overview
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.
## Features
### Dashboard Statistics
- **Main Statistics Dashboard** - Four color-coded tiles showing your most important Pi-hole metrics:
- Total DNS Queries
- Queries Blocked
- Block Percentage
- Domains on Blocklists
### Additional Metrics
- **Client Statistics** - See active clients, unique domains, unique clients, and time remaining
- **Performance Data** - View cached queries and forwarded DNS requests
- **Quick Access** - Hotlinks directly to Pi-hole admin pages for each statistic
### Direct Controls
- **Enable/Disable Controls** - Toggle Pi-hole filtering with a single click
- **Action Buttons** - Quick access buttons for common maintenance tasks:
- Refresh Data
- Restart DNS
- Update Gravity
- Flush ARP
- Flush Logs
### Version Information
- **Component Versions** - Display installed versions for all Pi-hole components:
- Core
- FTL
- Web Interface
- Home Assistant Integration
### Status Monitoring
- **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
### Interactive Dashboard
- **Clickable Links** - Direct links to the Pi-hole admin interface
- **Visual Indicators** - Color-coded statistics to understand status at a glance
> [!NOTE]
> This links to admin page only at the moment..
### Responsive Design
- **Mobile-friendly** - Optimized layout for both desktop and mobile viewing
- **Fluid Layout** - Responsive design adapts to available space
## Installation
### HACS (Recommended)
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-extras&repository=pi-hole-card&category=dashboard)
1. Open HACS in your Home Assistant instance
2. Click the menu icon in the top right and select "Custom repositories"
3. Add this repository URL and select "Dashboard" as the category
- `https://github.com/homeassistant-extras/pi-hole-card`
4. Click "Install"
### Manual Installation
1. Download the `pi-hole.js` file from the latest release in the Releases tab.
2. Copy it to your `www/community/pi-hole/` folder
3. Add the following to your `configuration.yaml` (or add as a resource in dashboards menu)
```yaml
lovelace:
resources:
- url: /local/community/pi-hole/pi-hole.js
type: module
```
## Usage
Add the card to your dashboard using the UI editor or YAML:
### Card Editor
The card is fully configurable through the card editor:
### YAML
This is the most minimal configuration needed to get started:
```yaml
type: custom:pi-hole
device_id: your_pihole_device_id
```
The 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
## Configuration Options
| Name | Type | Default | Description |
| --------- | ------ | ------------ | ---------------------------------------------------- |
| device_id | string | **Required** | The ID of your Pi-hole device in Home Assistant |
| url | string | _optional_ | URL to your Pi-hole admin interface for direct links |
### Auto-discovery
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.
## Example Configurations
### Basic Configuration
```yaml
type: custom:pi-hole
device_id: pi_hole_device_1
```
### With Custom URL
```yaml
type: custom:pi-hole
device_id: pi_hole_device_1
url: http://pi.hole
```
## Project Roadmap
- [x] **`Initial design`**: create initial card design
- [x] **`Auto-discovery`**: automatic detection of Pi-hole entities
- [x] **`Dashboard statistics`**: visual representation of key metrics
- [x] **`Control buttons`**: quick actions for common Pi-hole tasks
- [x] **`Version info`**: display component versions
- [ ] **`Links directly to sub pages`**: can't get links to sub pages to work yet..
## Contributing
- **💬 [Join the Discussions](https://github.com/homeassistant-extras/pi-hole-card/discussions)**: Share your insights, provide feedback, or ask questions.
- **🐛 [Report Issues](https://github.com/homeassistant-extras/pi-hole-card/issues)**: Submit bugs found or log feature requests for the `pi-hole` project.
- **💡 [Submit Pull Requests](https://github.com/homeassistant-extras/pi-hole-card/blob/main/CONTRIBUTING.md)**: Review open PRs, and submit your own PRs.
- **📣 [Check out discord](https://discord.gg/F28wupKC)**: Need further help, have ideas, want to chat?
- **🃏 [Check out my other cards!](https://github.com/orgs/homeassistant-extras/repositories)** Maybe you have an integration that I made cards for.
Contributing Guidelines
1. **Fork the Repository**: Start by forking the project repository to your GitHub account.
2. **Clone Locally**: Clone the forked repository to your local machine using a git client.
```sh
git clone https://github.com/homeassistant-extras/pi-hole-card
```
3. **Create a New Branch**: Always work on a new branch, giving it a descriptive name.
```sh
git checkout -b new-feature-x
```
4. **Make Your Changes**: Develop and test your changes locally.
5. **Commit Your Changes**: Commit with a clear message describing your updates.
```sh
git commit -m 'Implemented new feature x.'
```
6. **Push to GitHub**: Push the changes to your forked repository.
```sh
git push origin new-feature-x
```
7. **Submit a Pull Request**: Create a PR against the original project repository. Clearly describe the changes and their motivations.
8. **Review**: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!
## License
This project is protected under the MIT License. For more details, refer to the [LICENSE](LICENSE) file.
## Acknowledgments
- Built using [LitElement](https://lit.dev/)
- Inspired by Pi-hole's own dashboard design
- Thanks to all contributors!
[](https://github.com/homeassistant-extras/pi-hole-card/graphs/contributors)
[](https://ko-fi.com/N4N71AQZQG)
## Code Quality
Stats
[](https://sonarcloud.io/summary/new_code?id=homeassistant-extras_pi-hole-card)
[](https://sonarcloud.io/summary/new_code?id=homeassistant-extras_pi-hole-card)
[](https://sonarcloud.io/summary/new_code?id=homeassistant-extras_pi-hole-card)
[](https://sonarcloud.io/summary/new_code?id=homeassistant-extras_pi-hole-card)
[](https://sonarcloud.io/summary/new_code?id=homeassistant-extras_pi-hole-card)
[](https://sonarcloud.io/summary/new_code?id=homeassistant-extras_pi-hole-card)
[](https://sonarcloud.io/summary/new_code?id=homeassistant-extras_pi-hole-card)
Ratings
[](https://sonarcloud.io/summary/new_code?id=homeassistant-extras_pi-hole-card)
[](https://sonarcloud.io/summary/new_code?id=homeassistant-extras_pi-hole-card)
[](https://sonarcloud.io/summary/new_code?id=homeassistant-extras_pi-hole-card)
[](https://sonarcloud.io/summary/new_code?id=homeassistant-extras_pi-hole-card)
## Build Status
### Main
[](https://github.com/homeassistant-extras/pi-hole-card/actions/workflows/push.yml)
[](https://github.com/homeassistant-extras/pi-hole-card/actions/workflows/pull_request.yaml)
### Release
[](https://github.com/homeassistant-extras/pi-hole-card/actions/workflows/push.yml)
[](https://github.com/homeassistant-extras/pi-hole-card/actions/workflows/merge.yaml)