Config Screenshots

UCG-U with show_panel: true (default) [additional used background_opacity: 35]

USW-Lite-16-PoE with force_sequential_port: false (default) [additional used background_opacity: 35 / show_panel: false]

USW-Lite-16-PoE with force_sequential_port: true (optional) [additional used background_opacity: 35 / show_panel: false]

Normal AP Card Layout ap_compact_view: false (default) [additional used background_opacity: 35]

Compact AP Card Layout ap_compact_view: true (optional) [additional used background_opacity: 35]

A Home Assistant Lovelace custom card for UniFi switches, gateways, and access points — built on top of the official UniFi Network Integration.

No direct API access, no extra configuration. Just add the card and pick your device.

This dashboard is based on my idea, but was created with the help of ChatGPT and only tested with the UniFi devices I own:

• UCG-U
• US 8 60W
• USW Lite 8 PoE
• USW Lite 16 PoE
• USW Flex
• AC Mesh
• AC Pro
• U6+
• U6 Mesh

The idea behind this card was to create a single place to gather the most important information about UniFi devices, so you do not have to open the excellent UniFi app for every small detail. Since there was nothing like this available, I decided to get creative.

I try to save money to get an Cloud Gateway Max in future to replace my Cloud Gateway Ultra, maybe then i could be able to add more feature to the card.

If you see improvements, issues, or fixes, feel free to open an issue or create a pull request.

If you like this project and want to support my work, you can donate via PayPal.

• Realistic front-panel view — ports laid out close to the physical device, including dual-row, six-grid, quad-row, compact gateway, and special WAN/SFP slot layouts
• Device-accurate styling — white panel for Lite / Flex / Ultra / Cloud Gateway style devices, silver or dark layouts for rack devices like US 8 / UDM Pro / UDM SE
• Per-port link and PoE indication — visual port LEDs reflect link state, speed class, and active PoE
• Port detail panel — click any port to see link status, speed, PoE state, PoE power draw, RX/TX values, and available actions; disabling a port requires confirmation
• PoE toggle & Power Cycle — directly from the card when supported by Home Assistant entities
• Live port counter — connected / total shown in the header chip
• Automatic device detection — finds UniFi switches and gateways registered in Home Assistant
• Access Point card mode — AP devices render a dedicated AP panel with online status, uptime, clients, and reboot action (if available)
• Built-in UI editor — full card configuration without YAML
• Multi-language support — translations available for English, German, Dutch, French, Spanish, Italian, Swedish, Danish, Norwegian, Finnish, Polish, and Czech
• Supports renamed entities — port telemetry still works even if entities were renamed in Home Assistant
• Smarter link detection — falls back to speed, PoE power, and RX/TX traffic when direct port link entities are missing
• Optional card background color — use the default Home Assistant card background or override it with your own color
• Advanced color editor step — configure background/title/telemetry/labels/values/model+firmware/port labels/AP colors/button colors with live preview and per-slot reset
• AP-native card background behavior — AP cards can stay transparent like native Home Assistant cards unless a custom background color is configured

Unknown models are auto-detected by port count and fall back to a generic dark theme where possible.

• Access points are supported through a generic AP panel (status/uptime/clients/reboot)
• Some models are still layout-inferred if no dedicated registry entry exists
• WAN / SFP handling for UDM Pro and UDM SE was improved in v0.2.x
• US 16 PoE 150W and USW Pro 24 were added with dedicated layouts in v0.2.x

• Home Assistant with the UniFi Network Integration configured
• UniFi devices must appear under Settings → Devices & Services → UniFi

1. Open HACS
2. Go to Frontend
3. Search for UniFi Device Card
4. Install the card
5. Reload the browser/frontend

Use this path only if the card is not available through the normal HACS search, or if you want to install a development version, fork, or fallback source.

1. Open HACS
2. Go to Frontend
3. Click ⋮ → Custom repositories
4. Add:
   • Repository: https://github.com/bluenazgul/unifi-device-card
   • Category: Dashboard
5. Click Add
6. Search for UniFi Device Card and install the card
7. Reload the browser/frontend

1. Download unifi-device-card.js from the latest release
2. Copy to /config/www/unifi-device-card.js
3. Add the resource in HA under Settings → Dashboards → Resources:
   • URL: /local/unifi-device-card.js
   • Type: JavaScript module
4. Reload the browser

Add via the dashboard UI editor — search for UniFi Device Card — or manually:

type: custom:unifi-device-card
device_id: YOUR_DEVICE_ID
name: My Switch
background_color: "#1f2937"   # optional
title_color: "#ffffff"        # optional
telemetry_color: "#d1d5db"    # optional
label_color: "#9ca3af"        # optional
value_color: "#f3f4f6"        # optional
meta_color: "#94a3b8"         # optional (model + firmware line)
port_label_color: "#6b7280"   # optional
special_port_label_color: "#60a5fa" # optional (special/WAN label + detail headline)
ap_led_color: "#2563eb"       # optional fallback (AP only; used if RGB LED color is not available)
ap_color: "#e5e7eb"           # optional AP body color
ap_ring_color: "#cbd5e1"      # optional AP outer ring color
ap_inner_color: "#f8fafc"     # optional AP inner circle color
button_theme_style: true        # optional (default: true; use HA theme colors for buttons)
button_default_color: true      # optional (default when theme style is disabled)
button_color: "#0090d9"         # optional custom primary button background
button_text_color: "#ffffff"    # optional custom primary button text/icon color
button_secondary_color: "#262b34"      # optional custom secondary button background
button_secondary_text_color: "#e2e8f0" # optional custom secondary button text/icon color
button_border_color: "#3b4350"         # optional custom button border color
background_opacity: 85        # optional (0-100)
show_name: true               # optional (default: true)
show_telemetry: true          # optional (default: true; show CPU/memory/temperature in the header)
show_panel: true              # optional (default: true)
rotate180: false              # optional (default: false) | true flips the switch/gateway front panel by 180°
ports_per_row: 8              # optional (switches only)
force_sequential_ports: false # optional (switch/gateway only; disable odd/even layout)
port_size: 36                 # optional (switch/gateway front panel scale in px)
ap_scale: 100                 # optional (AP size in %, 25-140)
ap_compact_view: false        # optional (AP only; side-by-side compact AP layout)
ap_compact_show_header_telemetry: false # optional (AP only; show header telemetry also in compact AP view)
log_level: warn               # optional (error|warn|info|debug|trace)
debug: false                  # optional shorthand (true => debug log level)
edit_special_ports: false     # optional (switch/gateway only)
special_ports: [1, 2, 9]      # optional (switch/gateway only)
wan_port: auto                # optional (gateway only)
wan2_port: none               # optional (gateway only)

Header telemetry is read from Home Assistant's UniFi Network sensor entities. The card prefers the stable Home Assistant Core UniFi identifiers behind those entities, so renamed or localized CPU, memory, and temperature sensors can still be matched when Home Assistant exposes them.

If wan_port or wan2_port is set in YAML, edit_special_ports is automatically treated as enabled in the editor and persisted.

• port_*: sensor.*_link_speed can be used as a manual fallback if automatic mapping fails after port renaming in Home Assistant.
• Example: port_5: sensor.<device>_port_5_link_speed.
• Use this only when a renamed port is no longer automatically assigned to the correct physical port.
• Keep key and sensor port number aligned (for example port_5 → ..._port_5_link_speed) to avoid mismatched telemetry.

Open the browser console (F12) and check for errors.

Verify the resource URL is correct:

• HACS: /hacsfiles/unifi-device-card/unifi-device-card.js
• Manual: /local/unifi-device-card.js

Try a hard refresh (Ctrl+Shift+R).

Confirm the device appears under Settings → Devices & Services → UniFi.

The card can log runtime output in the browser console with UNIFI-DEVICE-CARD prefix and colorized levels.

Example:

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

For noisy traces, use log_level: trace. For quiet production usage, keep the default warn.

Check whether the UniFi Integration created matching entities for the device.

The card can use:

• direct link entities
• speed entities
• PoE power
• RX/TX traffic

Depending on the device model and firmware, not all signals may be available.

The card can only evaluate entities that Home Assistant actually provides.

If important UniFi entities are disabled, hidden, or not created by the integration, parts of the card may appear incomplete or incorrect.

For best results, make sure the relevant UniFi entities are enabled for the device, especially:

• port switch entities
• PoE switch entities
• PoE power sensors
• link speed sensors
• RX/TX traffic sensors
• power cycle buttons

In Home Assistant, check:

Settings → Devices & Services → UniFi → Devices / Entities

If required, enable the disabled entities there first.

Renamed entities are supported, but if Home Assistant entity registry data is stale, a reload of the integration or browser may help.

PoE controls are only shown if a PoE switch entity exists.

Ports that expose only poe_power sensors will still show consumption, but no PoE toggle button.

1. Check YAML syntax: port_<n>: sensor.*_link_speed.
2. Verify the referenced sensor exists and has state updates in Home Assistant.
3. Confirm key and sensor belong to the same physical port number (port_5 ↔ ..._port_5_link_speed).
4. Save YAML, reload dashboard/card, then verify mapping in the port detail panel.
5. If still wrong, open Developer Tools → States and verify the configured sensor.*_link_speed entity is available and updating for that exact device.

If remapping still fails after port renaming, the configured sensor.*_link_speed entity is usually missing, disabled, or still tied to a different physical port than expected.

If you want me to add clean support for a new device model, please include the following in your issue:

• UniFi device name as shown in Home Assistant / UniFi Controller
• UniFi model identifier (for example USW..., UCG..., UDM..., U7...)
• RJ45 port count (LAN/WAN if relevant)
• SFP/SFP+/SFP28 port count
• Optional but very helpful:
  • Which ports should be treated as special slots (WAN, WAN2, uplink)
  • Screenshot/photo of the physical front panel
  • Example entity IDs (especially switch.*_port_* and sensor.*_link_speed)

This is the minimum data needed to map the model correctly in model-registry.js and let helper logic in helpers.js detect and render ports reliably.

Check that:

• background_color is set in the card config
• the browser cache was refreshed
• the value is valid CSS, for example:
  • #1f2937
  • red
  • var(--card-background-color)