DNS Filter Card

Features

• Two cards: a full DNS Filter Card and a compact DNS Filter Mini Card, of type custom:dns-filter-card and custom:dns-filter-mini-card
• Three integrations: AdGuard Home, Pi-hole and Technitium DNS — automatic discovery, several instances supported, all can be mixed
• Sensors of your choice for any tile or counter (entities), for another DNS filter or a sensor of your own
• Four statistics tiles, one tint each: DNS queries, blocked queries, blocked ratio, and the average processing time (AdGuard Home) or the domains on the block lists (Pi-hole); each tile draws its last 24 hours behind it (recorder statistics, where the sensor keeps them)
• Detail counters: parental control, safe browsing and safe search blocks and the rules count (AdGuard Home); clients, unique domains, cached and forwarded queries, seen clients (Pi-hole)
• Status pill: protection on, protection off (AdGuard Home) or paused (Pi-hole), grey when unavailable; a click turns the AdGuard Home protection on or off, or pauses / resumes Pi-hole blocking
• AdGuard Home: the six setting switches as glass chips (protection, filtering, parental control, safe browsing, safe search, query log), a click toggles them; a refresh button updates the filter lists
• Pi-hole: a pause button opens a durations popup at the top of the card (5 min, 15 min, 30 min, 1 h, 2 h, or until resumed), a resume button while blocking is paused
• Versions in the footer (Core, FTL and web interface for Pi-hole) and an « Update available » chip for each pending update (click for its more-info dialog, where it can be installed)
• Detail button on the mini card (top right): it switches the mini card to the full card's content and back; a click anywhere outside the card brings the compact view back
• Click any value to open its Home Assistant history (more-info dialog)
• Round shield icon next to the name, in the status color, with the AdGuard or Pi-hole mark as a badge: a click opens the web interface of the instance (or the project's website when Home Assistant knows no address)
• Visual editor in the dashboard UI for both cards (no YAML needed)
• Light and dark mode, English, French, German, Spanish, Serbian (Cyrillic and Latin), Italian, Dutch, European Portuguese, Polish, Romanian, Danish, Swedish, Bulgarian, Russian, Ukrainian, Hungarian, Slovak, Czech, Slovenian, Latvian and Greek
• Single file, no external dependency

Supported integrations

Several instances are supported, and the integrations can be mixed: pick the instance in the visual editor.

Prerequisites

Home Assistant 2024.8 or later, and at least one of:

• the AdGuard Home integration (included in Home Assistant)
• the Pi-hole integration (included in Home Assistant)
• the Technitium DNS integration (Marketplace)

Configuration

Visual editor#

Edit a dashboard, click Add card and search for DNS Filter Card or DNS Filter Mini Card. The first instance found is preselected; pick another one in the list if you have several (AdGuard Home and Pi-hole instances are listed together), set an optional title, the web interface address, the sections to display and the language. The preview updates live, and options left at their default are kept out of the generated YAML.

Minimal#

type: custom:dns-filter-card

type: custom:dns-filter-mini-card

Full options#

type: custom:dns-filter-card
device: 3f2a9c1e7b6d4a8f9e0c1b2a3d4e5f67
title: AdGuard Home
url: http://192.168.1.2:3000
show_stats: true
show_details: true
show_switches: true
show_history: true
show_versions: true
language: fr

type: custom:dns-filter-mini-card
device: 3f2a9c1e7b6d4a8f9e0c1b2a3d4e5f67
title: Pi-hole
show_history: true
zoom: true
language: fr

Options reference#

How it works

The cards read the Home Assistant entity and device registries instead of entity ids: every entity of the adguard and pi_hole integrations is matched by its translation_key (dns_queries, dns_queries_blocked_ratio, average_processing_speed, ads_blocked, domains_being_blocked, core_update_available…) and grouped by the device it belongs to. Entity ids can therefore be in any language or renamed without breaking the cards.

• AdGuard Home: the status pill follows the Protection switch. The six switches of the integration become chips: a click calls switch.toggle. The refresh button at the bottom right calls the adguard.refresh action (filter lists, without force). The Rules count sensor is disabled by default by the integration: enable it in Settings → Devices & services → Entities to see it among the detail counters. The update entity of the integration shows an « Update available » chip while it is on.
• Technitium DNS: the integration gives no translation_key; its entities have fixed English names, hence entity ids ending the same whatever the language (_total_queries, _blocked_queries, _blocked_zones…). Only the server (device model "DNS Server") is an instance, not its DHCP clients. The ad blocking switch is the one switch of the server; the pause durations are its "Disable Ad Blocking for …" buttons, and « until resumed » turns the switch off. The blocked ratio is worked out from the blocked and total queries.
• Pi-hole: the status pill follows the Status binary sensor (on = blocking). The blocking switch carries no translation_key: it is the one switch of the device. The pause button calls the pi_hole.disable action with the chosen duration (00:30:00…), or turns the switch off for « until resumed »; the resume button turns it on again. Pi-hole v6 renamed its counters (dns_queries, ads_blocked, percent_ads_blocked): the former v5 keys (dns_queries_today, ads_blocked_today, ads_percentage_today) are read too. The three update entities carry the installed versions of Core, FTL and the web interface, shown in the footer.

Narrow cards#

The full card fits down to 9 columns of a sections view (about 234 px on a phone), the mini card down to 6 columns (about 156 px on a phone). Below about 240 px the statistics tiles stack in one column. Below about 200 px, the status pill shrinks to its colored dot (its text stays in its tooltip). In a container sized by its content (a grid auto column, an inline-block wrapper), the cards take a width of 400 px instead of collapsing.

Support

If you find this project useful, you can support its development:

Features

• show_title and show_subtitle options (also in the visual editor) hide the header's title and its subtitle, separately, for a card placed under a section heading of its own (asked in juju35/ha-vehicle-card#72).

Features

• Technitium DNS (#11): the technitiumdns integration of the Marketplace is found like AdGuard Home and Pi-hole: total and blocked queries, the blocked ratio worked out from both, blocked zones, clients, cached and recursive queries, the ad blocking switch, and the pause through its "Disable Ad Blocking for …" buttons (the durations it offers, or until resumed).
• Sensors of your choice: entities replaces the sensors found for a tile or a counter (queries, blocked, ratio, domains, clients…) and the blocking switch (protection).

Fixes

• Translations: the cards are defined once the page's language file has arrived (at most 1.5 s; Home Assistant builds a card when its element gets defined), so the first render is already translated instead of English then redrawn; until a language file is in, a missing text reads the English one wherever the card has no fallback of its own.

Performance

• Translations load on demand: the bundle keeps English only (114 KB → 70 KB) and each other language is its own dns-filter-card.i18n.<lang>.js file next to it, fetched the first time a card needs it. Home Assistant loads every dashboard resource on every dashboard, so each page used to download and parse all 22 languages to use one. Until a language file has arrived (a few milliseconds), texts fall back to English, and the cards redraw once it is there.

Maintenance

• Build: scripts/i18n-split.mjs splits the built bundle and rebuilds every table from the split files to check them (the build fails on any difference); src/ keeps every language as before.
• Release: every file of dist/ is attached. Manual installation copies the translation files too.

Changes

• The status pill no longer opens a more-info dialog: a click turns the AdGuard Home protection on or off, or pauses / resumes Pi-hole blocking (the tooltip says what the click does).

Fixes

• No focus ring left around the status pill or a tile after a mouse click opened its more-info dialog (keyboard use keeps it).