AdGuard Card

Complete AdGuard monitoring and control for Home Assistant

Built with the tools and technologies:

Overview

A comprehensive dashboard card for managing and monitoring your AdGuard DNS ad blocker directly from Home Assistant. The card provides real-time statistics in an intuitive, dashboard-style interface that matches the AdGuard visual identity.

Features

Dashboard Statistics

Main Statistics Dashboard - Four color-coded tiles showing your most important AdGuard metrics:
- Total DNS Queries
- Queries Blocked
- Block Percentage
- Domains on Blocklists

Additional Metrics

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

System Metrics Chart

CPU and Memory Usage Graph - Visualize your AdGuard's system resource usage over the last 24 hours:
- Real-time CPU usage tracking
- Memory consumption monitoring
- Historical data visualization
- Customizable line styles (normal, gradient, no fill)
Automatic Data Fetching - Chart automatically loads statistics data from Home Assistant's recorder
Responsive Design - Chart adapts to card width and displays smoothly on all devices

Direct Controls

Enable/Disable Controls - Toggle AdGuard filtering with a single click as well as Group Default

Version Information

Component Versions - Display installed versions for all AdGuard components:
- Core
- Docker
- FTL
- Web Interface
- Home Assistant Integration
- Last Refresh Time

Status Monitoring

Real-time Status - Visual indication of AdGuard's current state
Error Detection - Automatic highlighting when issues are detected
Update Indicators - Clear notification when updates are available
FTL Diagnostic Message Count - Shows diagnostic message count when more than 0
Interactive Diagnostic Management - Smart icon behavior based on diagnostic message count:
- When diagnostic messages exist: Tap to purge diagnostic messages, hold/double-tap for more info
- When no diagnostic messages: All interactions show more info about the diagnostic entity
- Custom Actions: Override default behavior with custom tap, hold, and double-tap actions

Interactive Dashboard

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)

Multi-AdGuard Support

Centralized Control - Manage multiple AdGuard instances from a single card
Aggregated Status - See at a glance how many of your AdGuard instances are active
Unified Control - Centralized access to all switches from your AdGuard 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-AdGuard feature currently has some limitations:

Statistics shown are from the first AdGuard instance in the list only
All switches from all AdGuard instances are displayed in a single list
Only header status reflects the multi-AdGuard state

Responsive Design

Mobile-friendly - Optimized layout for both desktop and mobile viewing
Fluid Layout - Responsive design adapts to available space

Installation

Prerequisites

Warning

Before using this card, please ensure you have the AdGuard integration installed in your Home Assistant instance.

HACS (Recommended)

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/adguard-card
Click "Install"

Manual Installation

Download the adguard-card.js file from the latest release in the Releases tab.
Copy it to your www/community/adguard-card/ folder
Add the following to your configuration.yaml (or add as a resource in dashboards menu)

lovelace:
  resources:
    - url: /local/community/adguard-card/adguard-card.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, allowing you to customize:

AdGuard device selection (single or multiple)
Card title and icon
Custom actions for statistics and info panels

YAML

This is the most minimal configuration needed to get started:

type: custom:adguard
device_id: your_adguard_device_id

For multiple AdGuard instances:

type: custom:adguard
device_id:
  - your_first_adguard_device_id
  - your_second_adguard_device_id
  - etc..

The card will automatically:

Detect all AdGuard entities associated with the device(s)
Organize statistics in the dashboard layout
Show version information for all components
For multiple AdGuard instances: combine switches and show aggregated status

Finding Your Device ID

If you're unsure what your AdGuard device ID is, here are several ways to find it:

Method 1: Use the Card Editor (Recommended)

Add the card through the visual editor
Select your AdGuard device from the dropdown
Click "Show Code Editor" or "View YAML" to see the generated configuration
Copy the device_id value for use in manual YAML configuration

Method 2: Devices Page

Go to Settings → Devices & Services → Devices
Search for "AdGuard" or browse to find your AdGuard device
Click on the device and look at the URL - the device ID will be in the URL path

Configuration Options

Name	Type	Default	Description
device_id	string or array	Required	The ID(s) of your AdGuard device(s) in Home Assistant
title	string	AdGuard	Custom title for the card header
icon	string	mdi:shield-check	Custom icon for the card header
badge	object	none	Configure actions for the card icon/badge
stats	object	none	Configure actions for statistics tiles
info	object	none	Configure actions for additional info items
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
styles	object	none	Custom CSS styles for card and sections. See below.
chart	object	none	Chart configuration options. See below.
features	list	See below	Optional flags to toggle different features

Action Configuration

Each section (stats, info) 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!

Section Options

The following section names can be used with exclude_sections:

chart
footer
header
statistics
sensors
switches

Collapse Options

The following section names can be used with collapsed_sections:

switches

Switch Spacing Options

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

Custom Styles

The card supports custom CSS styles for different areas, allowing you to completely customize the appearance:

type: custom:adguard
device_id: adguard_device_1
styles:
  card:
    border-radius: 20px
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%)
  section:
    background-color: rgba(0, 0, 0, 0.1)
    border-radius: 8px

CSS Variables

The following CSS variables can be used within the styles configuration for advanced customization:

Variable	Area	Description	Default
`--user--section--caret--display`	section	Control visibility of section caret icons	`block`

Example:

styles:
  section:
    --user--section--caret--display: none # Hide the collapse/expand arrows
    background-color: rgba(0, 0, 0, 0.1)
    padding: 10px

Chart Configuration

The chart option allows you to customize the appearance of the system metrics chart:

Name	Type	Default	Description
line_type	string	normal	Chart line style. Options: `normal`, `gradient`, `gradient_no_fill`, `no_fill`

Chart Line Types:

normal (default): Standard solid lines with filled areas
gradient: Gradient-colored lines with gradient-filled areas
gradient_no_fill: Gradient-colored lines without fill
no_fill: Solid lines without fill areas

Auto-discovery

The card automatically discovers and identifies all AdGuard 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

type: custom:adguard
device_id: adguard_device_1

Multiple AdGuard Configuration

type: custom:adguard
device_id:
  - adguard_device_1
  - adguard_device_2
title: 'My AdGuard Network'

With Custom Title and Icon

type: custom:adguard
device_id: adguard_device_1
title: 'My AdGuard Server'
icon: 'mdi:shield-check'

Excluding Sections & Entities

type: custom:adguard
device_id: adguard_device_1
exclude_sections:
  - sensors
  - switches
exclude_entities:
  - sensor.adguard_latest_data_refresh

With Custom Actions

type: custom:adguard
device_id: adguard_device_1
title: 'Network Protection'
stats:
  tap_action:
    action: more-info
  hold_action:
    action: navigate
    navigation_path: /lovelace/network

With Custom Badge Actions

The card icon/badge supports custom actions that can override the default diagnostic message behavior:

type: custom:adguard
device_id: adguard_device_1
badge:
  tap_action:
    action: navigate
    navigation_path: /lovelace/adguard-dashboard
  hold_action:
    action: call-service
    perform_action: browser_mod.popup
    data:
      title: AdGuard Status
      content: 'Quick overview of AdGuard status'
  double_tap_action:
    action: more-info
    entity_id: sensor.adguard_status

Note

Default Badge Behavior: If no custom badge actions are configured, the card will automatically show more info when tapping, holding, or double-tapping the badge icon.

Warning

Multi-AdGuard Action Behavior: When using multiple AdGuard instances, actions are executed for each configured AdGuard instance. This can lead to unexpected behavior:

More-info actions: Only one dialog can be open at a time, so you may only see info for the first or last AdGuard instance
Navigation actions: Multiple navigation attempts may conflict with each other
Service calls: Will be executed for all AdGuard instances, which may or may not be desired

Consider using single-entity actions or service calls with specific targeting when configuring multi-AdGuard setups.

Custom Actions for All Sections

type: custom:adguard
device_id: adguard_device_1
# Configure stat box actions
stats:
  tap_action:
    action: call-service
    perform_action: browser_mod.popup
    data:
      title: AdGuard Statistics
      content: 'Detailed view of AdGuard 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

Custom Entity Order & Switch Spacing

type: custom:adguard
device_id: adguard_device_1
switch_spacing: 'space-around'
entity_order:
  - button.adguard_action_refresh_data
  - sensor.adguard_dns_queries
  - sensor.adguard_dns_queries_blocked
  - switch.adguard

Entity Order with Dividers

type: custom:adguard
device_id: adguard_device_1
entity_order:
  - divider
  - sensor.adguard_dns_queries
  - sensor.adguard_dns_queries_blocked
  - divider
  - switch.adguard

Collapsed Sections

type: custom:adguard
device_id: adguard_device_1
collapsed_sections:
  - switches

Chart Configuration

type: custom:adguard
device_id: adguard_device_1
chart:
  line_type: gradient # Options: normal, gradient, gradient_no_fill, no_fill

Excluding Chart Section

type: custom:adguard
device_id: adguard_device_1
exclude_sections:
  - chart # Hide the system metrics chart

Project Roadmap

Contributing

💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
🐛 Report Issues: Submit bugs found or log feature requests for the adguard project.
💡 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/adguard-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!

Translations

The AdGuard card supports multiple languages to provide a better experience for users worldwide.

Currently supported languages:

English
Spanish
Greek
Italian

Want to contribute a translation? See our translation guide for instructions.

License

This project is protected under the MIT License. For more details, refer to the LICENSE file.

Name		Name	Last commit message	Last commit date
Latest commit History 176 Commits
.claude		.claude
.github		.github
assets		assets
src		src
test		test
.gitignore		.gitignore
.mocharc.json		.mocharc.json
.nycrc		.nycrc
.prettierrc		.prettierrc
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
TRANSLATIONS.md		TRANSLATIONS.md
hacs.json		hacs.json
mocha.setup.ts		mocha.setup.ts
package.json		package.json
sonar-project.properties		sonar-project.properties
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

AdGuard Card

AdGuard Card

Overview

Features

Dashboard Statistics

Additional Metrics

System Metrics Chart

Direct Controls

Version Information

Status Monitoring

Interactive Dashboard

Multi-AdGuard Support

Responsive Design

Installation

Prerequisites

HACS (Recommended)

Manual Installation

Usage

Card Editor

YAML

Finding Your Device ID

Method 1: Use the Card Editor (Recommended)

Method 2: Devices Page

Configuration Options

Action Configuration

Section Options

Collapse Options

Switch Spacing Options

Custom Styles

CSS Variables

Chart Configuration

Auto-discovery

Example Configurations

Basic Configuration

Multiple AdGuard Configuration

With Custom Title and Icon

Excluding Sections & Entities

With Custom Actions

With Custom Badge Actions

Custom Actions for All Sections

Custom Entity Order & Switch Spacing

Entity Order with Dividers

Collapsed Sections

Chart Configuration

Excluding Chart Section

Project Roadmap

Contributing

Translations

Currently supported languages:

License

Acknowledgments

Code Quality

Build Status

Main

Release

Other

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Uh oh!

Contributors 0

Languages

Packages

Contributors