Skip to content
github-actions[bot] edited this page Nov 9, 2026 · 12 revisions

Icons

Muximux supports four types of icons for apps and groups: Dashboard Icons, Lucide Icons, Custom Icons, and URL Icons.

Dashboard Icons

Over 600 icons for popular self-hosted applications, sourced from the dashboard-icons project by Homarr Labs.

icon:
  type: dashboard
  name: plex          # Icon name (matches the service name)
  variant: light      # light, dark, or empty for default

Configuration

You configure dashboard icon behavior in the icons section of config.yaml:

icons:
  dashboard_icons:
    cache_dir: icons/dashboard   # Where fetched icons are stored
    cache_ttl: 7d                # How long a cached icon is reused before refetch

Muximux downloads a dashboard icon the first time it is requested, and caches it locally under cache_dir. Later loads come from the cache until cache_ttl expires. Muximux then fetches the icon again. The first load of each icon has a slight delay. After that, it is instant.

Lucide Icons

Over 1,600 open-source icons from the Lucide icon library. They are SVG icons in a consistent style, organized by category.

icon:
  type: lucide
  name: server        # Lucide icon name

Muximux fetches Lucide icons from the jsDelivr CDN (a public content delivery network) and caches them locally. They work well for generic icons (settings, home, play, download, folder, etc.). Use them when dashboard-icons does not have a match for your app.

The list of icon names comes from the Lucide repository on GitHub (api.github.com). The categories for the picker's filter come from https://lucide.dev/api/categories. If only the category request fails, Muximux still lists the icons, without categories. It logs a warning once (see Troubleshooting). If the request for the icon names also fails, and no cached list is available, the Lucide icon list is not available.

Custom Icons

Upload your own icons (PNG, SVG, JPG, WebP, GIF) through the Settings panel or API.

icon:
  type: custom
  file: my-custom-icon.png    # Filename in data/icons/custom/

Upload limits: 2MB per icon. Admin role required.

Muximux stores custom icons in the data/icons/custom/ directory and serves them at /icons/custom/{filename}.

You can add custom icons in three ways:

  1. File upload -- Through the Settings panel icon browser (click "Upload" in the Custom tab)
  2. Fetch from URL -- Paste an image URL in the Custom tab and click "Fetch". The server downloads the image, validates it, and saves it locally as a custom icon. This is the recommended way to use icons from external sources. Muximux stores the image locally, so the icon does not break if the remote server goes down.
  3. API -- POST /api/icons/custom (multipart upload) or POST /api/icons/custom/fetch (download from URL)

URL Icons

Reference any external image URL as an icon. This is a power-user option for manual config.yaml editing.

icon:
  type: url
  url: https://example.com/icon.png

Useful for apps that provide their own favicon or icon URL.

Note: The URL must be accessible from the user's browser, not from the Muximux server. The browser loads URL icons directly. So the image host must be reachable from wherever your users are browsing.

Prefer fetching over hotlinking (loading the image straight from another site). URL icons break if the remote server goes down or the image moves. The icon browser's Fetch from URL feature (in the Custom tab) downloads the image and stores it locally. This avoids the problem. Use type: url only when you need a live reference to an image that changes externally.

Icons from Docker Labels

With Docker Discovery, the muximux.app.icon and muximux.group.icon labels pick an icon for an imported app or a Docker-created group. A label can name a Dashboard Icons slug (sonarr or dashboard:sonarr), a Lucide icon (lucide:shield-check) or an https URL. A label cannot name a custom upload. See Icon label formats.

Icon Appearance Options

All icon types support optional appearance customization:

icon:
  type: dashboard
  name: sonarr
  variant: light
  color: "#ff9600"        # Tint color (Lucide icons only)
  background: "#1a1a2e"   # Background color behind the icon
  invert: true            # Invert icon colors (swap dark ↔ light)

Color

The color field applies a color tint to Lucide icons. It has no effect on other icon types. Dashboard, custom and URL icons already have their own colors baked in.

Background

The background field sets a custom background color behind the icon. By default, Muximux uses the app's accent color as the icon background. background overrides that default for the icon only. It does not change the app's accent color elsewhere (tab indicator, sidebar highlight).

The background shows only when show_icon_background is enabled in the navigation settings. An app with force_icon_background: true always shows it.

Invert

The invert field flips the icon's colors. It turns light icons dark and dark icons bright. This is useful when a dashboard icon only comes in a variant that clashes with your theme. For example, an app may only provide a white-on-transparent icon while you use a light theme. Then invert: true makes the icon visible.

Icon Browser

The Settings panel includes an icon browser. It lets you search and preview icons from all available sources. You can:

  • Search icons by name across all sources
  • Filter by source (Dashboard, Lucide, Custom)
  • Preview icons before selecting them
  • See available variants for dashboard icons (light, dark, default)
  • Upload new custom icons directly from the browser
  • Fetch icons from a URL (downloaded and stored locally)

To open the icon browser:

  1. Edit any app or group in Settings.
  2. Click the icon field.

Clone this wiki locally