UniFi Device Card

A Home Assistant Lovelace custom card for UniFi switches, gateways, access points, UPS devices, and SmartPower outlets. It uses the UniFi Network integration, which is included with Home Assistant, and the entities already registered in Home Assistant.

Add the card, pick a device, and configure common settings in the visual editor. YAML provides additional overrides for port names, LAG badges, link colors, and sensor mappings.

Requirements · Installation · Usage and YAML examples · Configuration options · Supported devices · Troubleshooting · Screenshots · Development

Features

• Model-specific front panels with RJ45/SFP link-speed and PoE indicators, port details, and available port controls.
• Access point layouts with status, uptime, clients, and reboot controls; supported hybrid devices also offer combined or network-only views.
• UPS front/back views with available battery/runtime readings and outlet controls; SmartPower Strip/PDU outlet overviews with AC/USB relays.
• Console outlet names, optional power badges, off confirmation, and visible command/state feedback.
• Automatic device and entity discovery, including renamed entities through stable UniFi identifiers.
• A visual editor, custom colors, optional link LED animation, and configurable port/outlet detail behavior.
• Automatic Sections sizing with optional Home Assistant grid_options overrides.
• Translations for English, German, Dutch, French, Spanish, Italian, Swedish, Danish, Norwegian, Finnish, Polish, and Czech.

Requirements

• Home Assistant Core 2026.9.0 or newer with the built-in UniFi Network integration configured
• UniFi devices must appear under Settings → Devices & Services → UniFi Network

[!IMPORTANT]

Starting with v1.0.0, upgrade Home Assistant to 2026.9.0 or newer before updating the card. If you need to stay on an older Home Assistant version, keep the latest compatible v0.8.x card release.

Existing card YAML and device selections do not need to be changed. Features still depend on the entities exposed by your configured UniFi Network integration; for example, UniFi UPS telemetry requires Home Assistant Core 2026.10 or newer.

Installation

HACS

1. Open HACS and search for UniFi Device Card in the Dashboard category.
2. Install the card and reload the browser/frontend.
3. Add UniFi Device Card to your dashboard and select your device.

Older Home Assistant versions

HACS checks the minimum Home Assistant version in the selected release's hacs.json. v1.x requires Home Assistant Core 2026.9.0 or newer; older v0.8.x releases retain their own requirements. HACS defaults to the newest release and does not automatically select the newest compatible version.

To install or keep a compatible v0.8.x release on an older Home Assistant version:

1. Find UniFi Device Card in HACS and open its ⋮ menu.
2. Select Download for a first installation or Redownload if the card is already installed.
3. Expand Need a different version? and select a compatible v0.8.x release, such as v0.8.9.
4. Download it and reload the browser/frontend.

HACS currently lists only the latest 30 releases, so an older v0.8.x release may eventually disappear from the selection menu. Its GitHub release assets remain available: download unifi-device-card.js from the compatible release and follow the manual installation steps below.

Manual installation

1. Download unifi-device-card.js from the latest release, or from a compatible v0.8.x release if your Home Assistant version is below 2026.9.0.
2. Copy it to /config/www/unifi-device-card.js.
3. Add a resource under Settings → Dashboards → Resources, with URL /local/unifi-device-card.js and type JavaScript module.
4. Reload the browser and add the card to your dashboard.

Usage and YAML examples

Start with the visual editor, or use this minimal YAML configuration:

type: custom:unifi-device-card
device_id: YOUR_DEVICE_ID

device_id is the Home Assistant device registry ID, not an entity ID or MAC address. Select the device in the editor to populate it, or copy the final ID from its Settings → Devices & Services device-page URL.

The examples below are separate card configurations. Replace placeholder device/entity IDs with your own and choose options that apply to your model.

Switch: names, LAG badges, and link LEDs

type: custom:unifi-device-card
device_id: YOUR_SWITCH_DEVICE_ID
name: Office switch
default_uplink_port: auto
dynamic_port_details: false
port_name:
  1: Uplink
  3: Office AP
lag_groups:
  - name: NAS
    ports: [11, 12]
port_led_blink: true
port_led_blink_speed_rj45: 0.2
port_led_blink_speed_sfp: 0.5
link_color_10-100: "#efb21a"
link_color_1000: green
link_color_2.5g: orange
link_color_10g: white

Use physical port numbers that exist on your switch. port_name changes tooltips/detail headings; the printed front-panel port numbers stay unchanged. lag_groups adds visual badges only: configure the actual aggregation in UniFi Network. Blink intervals are seconds, so 0.2 means 5 blinks per second.

default_uplink_port: auto prefers an active designated uplink, then the first designated uplink, then the first port. For a specific initial port, use an exact selectable key from the editor; gateway wan_port selectors and manual port_ sensor mappings use different keys. Dynamic port details start with no selection and override initial port selection.

Special row: replace or extend the model defaults

To replace the special row with physical ports 17 and 18 on a compatible switch:

type: custom:unifi-device-card
device_id: YOUR_SWITCH_DEVICE_ID
edit_special_ports: true
special_ports: [17, 18]

An empty special_ports: [] removes the special row in edit mode. To keep the model defaults and add ports 1 and 2 instead:

type: custom:unifi-device-card
device_id: YOUR_SWITCH_DEVICE_ID
edit_special_ports: false
custom_special_ports: [1, 2]

These settings affect the display. They do not configure uplinks or change the device's UniFi port roles. custom_special_ports is ignored while edit mode is enabled.

Gateway: assign WAN display roles

type: custom:unifi-device-card
device_id: YOUR_GATEWAY_DEVICE_ID
edit_special_ports: true
wan_port: port_5
wan2_port: none

Select physical ports or slot keys offered by the editor for your gateway. auto keeps the model's default assignment; none removes a WAN/WAN2 display role. WAN settings change the card's layout, not the gateway's network configuration.

When the editor saves a non-auto wan_port or wan2_port value, it enables and persists edit_special_ports. The additive custom_special_ports option no longer applies after enabling edit mode.

Access point: compact or integrated layout

type: custom:unifi-device-card
device_id: YOUR_AP_DEVICE_ID
ap_compact_view: true
ap_scale: 90
show_telemetry: true
ap_compact_show_header_telemetry: true

For supported multi-port APs or hybrid gateway/AP devices, use device_layout: combined, network, or ap. Integrated AP port panels require at least two discovered ports. The older integrated_ports: false option selects AP-only mode when device_layout is unset.

Custom card and button colors

type: custom:unifi-device-card
device_id: YOUR_DEVICE_ID
background_color: "#1f2937"
background_opacity: 85
title_color: "#ffffff"
telemetry_color: "#d1d5db"
label_color: "#9ca3af"
value_color: "#f3f4f6"
meta_color: "#94a3b8"
button_theme_style: false
button_default_color: false
button_color: "#0090d9"
button_text_color: "#ffffff"
button_secondary_color: "#262b34"
button_secondary_text_color: "#e2e8f0"
button_border_color: "#3b4350"

Custom button colors require both button_theme_style: false and button_default_color: false. Other card colors are independent. Link LED overrides accept CSS color names or hex values; normal card color options also accept CSS tokens such as var(--primary-color).

UPS and SmartPower outlets

type: custom:unifi-device-card
device_id: YOUR_UPS_DEVICE_ID
ups_layout: back
show_back_panel: false
dynamic_port_details: false
dynamic_outlet_details: true
outlet_power_badges: true
confirm_outlet_off: true

ups_layout selects a UPS front, back, or combined view. For SmartPower Strip/PDU, omit ups_layout; these devices always use the outlet overview. show_back_panel: false removes the outlet-panel background while keeping outlets visible.

Select an outlet, then use its separate on/off button. Labels prefer the Console names supplied by the integration. Real cards show only registered outlets; model/preview outlet counts do not create controllable outlets. A missing or unavailable relay cannot be controlled, while metering-only outlets can still show power.

dynamic_outlet_details controls outlet selection independently of RJ45 details. When unset, it inherits dynamic_port_details for compatibility. In the example, UPS RJ45 details remain visible until an outlet is selected and return when it is deselected. Set both dynamic options to true to initially collapse both kinds of details.

To start with a specific outlet selected, use:

type: custom:unifi-device-card
device_id: YOUR_UPS_OR_SMARTPOWER_DEVICE_ID
dynamic_outlet_details: false
default_outlet: 3
outlet_power_badges: true

default_outlet uses the registered outlet index and falls back to the first available outlet if that index is missing. It is ignored while dynamic outlet details are enabled.

Outlet commands wait for Home Assistant to confirm the new state. Failures and missing confirmation after 10 seconds are displayed in the outlet details. confirm_outlet_off asks before turning an outlet off; turning it on requires no confirmation.

Readings depend on the entities exposed by your Home Assistant/UniFi version. Missing Strip/USB metering is normal. UPS battery/runtime readings and indicators follow the available telemetry; show_telemetry: false hides header/UPS readings while keeping outlet readings available. Load percentage requires matching whole-device AC consumption and a positive power budget in W/kW. The card does not infer load from model ratings or individual outlet readings.

The editor distinguishes disabled entities, unavailable states, and entities not exposed by the integration. Hidden enabled outlet entities remain usable.

Manual link-speed sensor mapping

Use a manual override only when automatic port mapping fails:

type: custom:unifi-device-card
device_id: YOUR_DEVICE_ID
port_5: sensor.office_switch_port_5_link_speed

The key identifies an existing physical port. The referenced sensor must belong to that port and be enabled/available in Home Assistant. The card may find matching RX/TX and PoE entities with the same sensor-name prefix, but the override does not create missing entities.

Local model previews

Enable Fake Device in the editor and select a model to preview its layout without real hardware. Preview outlet controls change local example states and never call Home Assistant services. The editor stores fake_device: true and the corresponding fake: device ID; turn preview mode off before selecting a real device.

Configuration options

Unset options use the defaults below. Model-specific settings take effect only where the relevant layout or entities exist. The table identifies YAML-only options and retained compatibility aliases.

General and card layout

| Key | Type | Default | Description | |---|---|---|---| | device_id | string | — | Home Assistant device registry ID of the UniFi device. | | name | string | device name | Custom display name shown in card header (if show_name is enabled). | | show_name | boolean | true | Show/hide the header title line. | | show_telemetry | boolean | true | Show/hide header telemetry. On UPS cards, also controls the battery summary, battery indicators, and UPS readings; on SmartPower cards, controls whole-device AC readings. Outlet readings remain available. | | show_panel | boolean | true | Show/hide the visual front panel area. | | background_opacity | number | 100 | Background transparency in percent (0 = transparent, 100 = opaque). | | grid_options | object | automatic | Home Assistant Sections layout override, for example {columns: 24, rows: auto}. This option is handled by Home Assistant. |

Colors and button style

| Key | Type | Default | Description | |---|---|---|---| | background_color | string | var(--card-background-color) | Any valid CSS color/token. | | title_color | string | theme default | Optional title text color. | | telemetry_color | string | theme default | Optional header telemetry color (including device-specific UPS/AC readings). | | label_color | string | theme default | Optional detail/panel label color. | | value_color | string | theme default | Optional detail value color (except fixed link-status state colors). | | meta_color | string | theme default | Optional model/firmware subtitle color. | | port_label_color | string | theme default | Optional front-panel port number label color. | | special_port_label_color | string | theme default | Optional special-port label color (for special row labels like WAN and the selected special port headline). | | ap_led_color | string | model default | AP only: optional LED fallback color used when no RGB LED color is provided by entities. | | ap_color | string | model default | AP only: optional AP body color override. | | ap_ring_color | string | model default | AP only: optional AP outer ring color override. | | ap_inner_color | string | model default | AP only: optional AP inner circle color override. | | button_theme_style | boolean | true | Use Home Assistant theme colors for card buttons. | | button_default_color | boolean | true | Use the card's built-in default button colors when theme button style is disabled. | | button_color | string | default/theme | Custom button background color when theme and default button colors are disabled. | | button_text_color | string | default/theme | Custom button text/icon color when theme and default button colors are disabled. | | button_secondary_color | string | default/custom primary | Optional custom secondary button background color. | | button_secondary_text_color | string | default/custom primary | Optional custom secondary button text/icon color. | | button_border_color | string | default/theme | Optional custom secondary button border color. | | link_color_10-100 | string | amber | YAML-only link LED color override for 10/100 Mbps; accepts a CSS color word or hex value. | | link_color_1000 | string | green | YAML-only link LED color override for 1 GbE; accepts a CSS color word or hex value. | | link_color_2.5g | string | amber | YAML-only link LED color override for 2.5 GbE; accepts a CSS color word or hex value. | | link_color_10g | string | white | YAML-only link LED color override for both 5 and 10 GbE; accepts a CSS color word or hex value. |

Network ports

| Key | Type | Default | Description | |---|---|---|---| | dynamic_port_details | boolean | false | Network port details, including UPS management ports: starts without a selected port, shows details after a port click, and hides them when that port is clicked again. | | default_uplink_port | string | unset | Switch/Gateway and compatible In-Wall AP port sections: initial detail port behavior. Leave unset for the existing first-port behavior, use auto to prefer an active selectable port, or copy a selectable port key from the editor (for example sfp_1 or uplink; keys depend on the model). Ignored while dynamic port details are enabled. Switches and gateways restrict choices to designated uplinks. | | port_name | object | {} | YAML-only port-number-to-name mapping for tooltips and detail headings. Front-panel port numbers remain unchanged. | | lag_groups | array