Skip to main content
Homarr includes a powerful icon picker with access to over 10,000 icons from multiple popular icon repositories. Customize your apps and widgets with the perfect icon, or use custom URLs for brand-specific icons.

Icon Picker

The icon picker provides an intuitive interface for selecting icons:

Opening the Icon Picker

1

Edit App or Widget

Click the edit button on an app or widget that supports custom icons.
2

Click Icon Field

Click on the current icon or the “Select Icon” button.
3

Browse or Search

The icon picker modal opens with thousands of icons organized by repository.
4

Select Icon

Click an icon to select it, then save your changes.

Icon Repositories

Homarr sources icons from multiple high-quality repositories:
// From packages/icons/src/icons-fetcher.ts:6
const repositories = [
  new GitHubIconRepository(
    "Dashboard Icons",
    "homarr-labs/dashboard-icons",
    undefined,
    new URL("https://github.com/homarr-labs/dashboard-icons"),
    new URL("https://api.github.com/repos/homarr-labs/dashboard-icons/git/trees/main?recursive=true"),
    "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/{0}"
  ),
  new GitHubIconRepository(
    "selfh.st",
    "selfhst/icons",
    "CC0-1.0",
    new URL("https://github.com/selfhst/icons"),
    new URL("https://api.github.com/repos/selfhst/icons/git/trees/main?recursive=true"),
    "https://cdn.jsdelivr.net/gh/selfhst/icons/{0}"
  ),
  new GitHubIconRepository(
    "SimpleIcons",
    "simple-icons/simple-icons",
    "CC0-1.0",
    new URL("https://github.com/simple-icons/simple-icons"),
    new URL("https://api.github.com/repos/simple-icons/simple-icons/git/trees/master?recursive=true"),
    "https://cdn.simpleicons.org/{1}"
  ),
  new JsdelivrIconRepository(
    "Papirus",
    "PapirusDevelopmentTeam/papirus-icon-theme",
    "GPL-3.0",
    new URL("https://github.com/PapirusDevelopmentTeam/papirus-icon-theme"),
    new URL("https://data.jsdelivr.com/v1/packages/gh/PapirusDevelopmentTeam/papirus_icons@master?structure=flat"),
    "https://cdn.jsdelivr.net/gh/PapirusDevelopmentTeam/papirus_icons/{0}"
  ),
  new JsdelivrIconRepository(
    "Homelab SVG assets",
    "loganmarchione/homelab-svg-assets",
    "MIT",
    new URL("https://github.com/loganmarchione/homelab-svg-assets"),
    new URL("https://data.jsdelivr.com/v1/packages/gh/loganmarchione/homelab-svg-assets@main?structure=flat"),
    "https://cdn.jsdelivr.net/gh/loganmarchione/homelab-svg-assets/{0}"
  ),
  new LocalIconRepository()
];

Repository Details

Description: High-quality icons for self-hosted applications and services.Size: 500+ iconsStyle: Clean, minimalist designBest for: Homelab applications and servicesLicense: CC0-1.0 (Public Domain)Format: SVGExample icons: AdGuard, Authelia, Bazarr, Calibre, Dashy, Frigate, Grafana, Homer
Description: Massive collection of brand icons for popular services and companies.Size: 2,500+ iconsStyle: Official brand logos and marksBest for: Popular services with established brands (GitHub, Docker, Google, etc.)License: CC0-1.0 (Public Domain)Format: SVGExample icons: GitHub, GitLab, Docker, npm, Kubernetes, Reddit, Discord, Slack, Spotify
Description: Comprehensive icon theme with thousands of application icons.Size: 5,000+ iconsStyle: Colorful, detailed icons with a unified lookBest for: Linux applications and general softwareLicense: GPL-3.0Format: SVGExample icons: Firefox, Chrome, VLC, GIMP, Steam, Telegram, Thunderbird
Description: Vector icons designed for homelab and infrastructure diagrams.Size: 200+ iconsStyle: Technical, diagrammatic styleBest for: Infrastructure components, network devices, serversLicense: MITFormat: SVGExample icons: Servers, routers, switches, storage, virtual machines
Description: Upload your own custom icons to Homarr.Size: Unlimited (storage dependent)Style: Your choiceBest for: Custom applications, internal services, personal brandingLicense: Your responsibilityFormat: SVG, PNG, JPG, WebPUpload: Settings → Icons → Upload

Searching for Icons

The icon picker includes powerful search functionality: Type in the search box to filter icons by name:
Search: "plex"
Results: Plex icons from all repositories
Homarr can automatically suggest icons based on app name:
// From packages/icons/src/auto-icon-searcher.ts
export class AutoIconSearcher {
  async searchForAppName(appName: string): Promise<IconResult[]> {
    // Normalize app name (remove spaces, lowercase, etc.)
    const normalizedName = this.normalizeAppName(appName);
    
    // Search across all repositories
    const results = await Promise.all(
      repositories.map(repo => repo.searchAsync(normalizedName))
    );
    
    // Combine and rank results
    return this.rankResults(results.flat(), normalizedName);
  }
  
  private normalizeAppName(name: string): string {
    return name
      .toLowerCase()
      .replace(/[^a-z0-9]/g, "")
      .trim();
  }
}
Features:
  • Fuzzy matching for typos
  • Synonym support (“jelly” matches “jellyfin”)
  • Multi-word handling
  • Priority ranking (exact matches first)

Repository Filtering

Filter icons by repository:
  1. Open icon picker
  2. Click Filter by Repository
  3. Select one or more repositories
  4. Only icons from selected repositories will show

Custom Icon URLs

Use any image URL as an icon:

Using Custom URLs

1

Open Icon Picker

Click the icon field to open the picker.
2

Switch to URL Tab

Click the Custom URL tab at the top.
3

Enter URL

Paste the full URL to your icon image:
https://example.com/my-icon.png
4

Preview and Save

The icon preview updates automatically. Click Save when satisfied.

Supported Image Formats

Vector Formats

SVG (Recommended)
  • Scalable to any size
  • Small file size
  • Best quality
  • Supports transparency

Raster Formats

PNG (Good)
  • Supports transparency
  • Good quality
  • Larger file size
WebP (Good)
  • Modern format
  • Small file size
  • Good quality
JPG (Acceptable)
  • No transparency
  • Small file size
  • Lower quality
GIF (Not Recommended)
  • Large file size
  • Limited colors
  • Use PNG instead

Custom URL Requirements

URL Requirements:
  • Must be publicly accessible
  • Should use HTTPS
  • Must be direct image link (not HTML page)
  • Recommended size: 256x256px or SVG
  • Should load quickly (less than 1MB recommended)

CDN URLs

Use CDN URLs for better performance:
  • jsDelivr: https://cdn.jsdelivr.net/gh/user/repo@version/path/to/icon.svg
  • GitHub Raw: https://raw.githubusercontent.com/user/repo/branch/path/to/icon.svg
  • Imgur: https://i.imgur.com/image-id.png
  • Cloudinary: https://res.cloudinary.com/account/image/upload/icon.png
Avoid using icons from sites that may go offline or require authentication. Use reliable CDNs or upload icons locally.

Uploading Local Icons

Upload custom icons directly to Homarr:

Upload Process

1

Navigate to Icon Settings

Go to SettingsIconsUpload
2

Select Files

Click Upload Icons and select one or more image files.Supported formats: SVG, PNG, JPG, WebP
3

Add Metadata

For each icon:
  • Enter a name
  • Add tags for easier search
  • Optionally add description
4

Save

Click Upload to add icons to your local repository.

Local Icon Management

  • View: Browse all uploaded icons
  • Search: Find icons by name or tag
  • Edit: Update name, tags, description
  • Delete: Remove unused icons
  • Export: Download icons for backup

Storage Considerations

File Size

  • SVG: 1-10 KB (recommended)
  • PNG: 10-100 KB (acceptable)
  • Large images: 100+ KB (avoid)
Optimize images before upload:
  • Use SVGO for SVGs
  • Use TinyPNG for PNGs
  • Resize to 256x256px max

Storage Limits

Default limits:
  • 100 MB total for local icons
  • Configurable in settings
  • Consider external CDN for large collections
Monitor usage:
  • Check storage in settings
  • Remove unused icons
  • Compress where possible

Icon Best Practices

Selection

  • Use icons from Dashboard Icons first (best compatibility)
  • Choose SVG over raster formats when available
  • Prefer official brand logos for recognizability
  • Ensure icon is recognizable at small sizes (32x32px)
  • Test on both light and dark themes

Custom Icons

  • Use consistent style across all custom icons
  • Maintain aspect ratio (preferably square)
  • Use transparent backgrounds
  • Optimize file size before uploading
  • Test loading speed

Organization

  • Use descriptive names for uploaded icons
  • Tag icons with categories (media, monitoring, etc.)
  • Group related icons together
  • Document custom icon sources
  • Back up local icons regularly

Performance

  • Prefer CDN URLs over self-hosted
  • Use SVG for vector graphics
  • Compress raster images
  • Avoid external URLs that may be slow or unreliable
  • Monitor icon loading times

Icon Repository Types

Homarr supports multiple repository implementations:

GitHub Repository

// From packages/icons/src/repositories/github.icon-repository.ts
export class GitHubIconRepository extends IconRepository {
  async getAllIconsAsync(): Promise<RepositoryIconGroup> {
    // Fetch tree from GitHub API
    const response = await fetch(this.treeUrl);
    const tree = await response.json();
    
    // Filter for icon files
    const icons = tree.tree
      .filter(item => this.isIconFile(item.path))
      .map(item => ({
        name: this.extractIconName(item.path),
        url: this.formatIconUrl(item.path),
        path: item.path
      }));
    
    return {
      name: this.repositoryName,
      icons,
      license: this.license
    };
  }
}
Benefits:
  • Direct access to GitHub repositories
  • Automatic updates when repository changes
  • Version pinning support
  • Free CDN via jsDelivr

jsDelivr Repository

// From packages/icons/src/repositories/jsdelivr.icon-repository.ts
export class JsdelivrIconRepository extends IconRepository {
  async getAllIconsAsync(): Promise<RepositoryIconGroup> {
    // Fetch package file list from jsDelivr
    const response = await fetch(this.apiUrl);
    const data = await response.json();
    
    // Map files to icons
    const icons = data.files
      .filter(file => this.isIconFile(file))
      .map(file => ({
        name: this.extractIconName(file),
        url: this.formatIconUrl(file)
      }));
    
    return {
      name: this.repositoryName,
      icons,
      license: this.license
    };
  }
}
Benefits:
  • Fast CDN delivery
  • Supports npm packages
  • Automatic caching
  • High availability

Local Repository

// From packages/icons/src/repositories/local.icon-repository.ts
export class LocalIconRepository extends IconRepository {
  async getAllIconsAsync(): Promise<RepositoryIconGroup> {
    // Load from database
    const icons = await db.icon.findMany({
      where: { repository: "local" }
    });
    
    return {
      name: "Local Icons",
      icons: icons.map(icon => ({
        name: icon.name,
        url: `/api/icons/${icon.id}`,
        tags: icon.tags
      })),
      license: null // User's responsibility
    };
  }
}
Benefits:
  • Full control over icons
  • No external dependencies
  • Custom icons not available elsewhere
  • Private/internal branding

Troubleshooting

Check:
  • Icon URL is accessible
  • CORS allows loading from Homarr domain
  • Image file exists and is valid
  • Network connectivity
Solution:
  • Test URL in browser directly
  • Use CDN URLs instead of direct links
  • Upload icon locally
  • Check browser console for errors
Check:
  • Internet connectivity (for external repositories)
  • Icon repositories are configured
  • No network/firewall blocking requests
  • Cache not corrupted
Solution:
  • Check network connectivity
  • Clear icon cache in settings
  • Restart Homarr
  • Check server logs
Check:
  • Icon resolution is adequate (minimum 128x128)
  • SVG preferred over raster
  • Browser zoom level
  • Display scaling
Solution:
  • Use SVG format
  • Upload higher resolution icon
  • Use icons from Dashboard Icons repository
  • Test at 100% zoom
Check:
  • File format is supported (SVG, PNG, JPG, WebP)
  • File size under limit
  • Storage space available
  • Sufficient permissions
Solution:
  • Compress image before upload
  • Convert to SVG if possible
  • Check storage limit in settings
  • Verify user permissions

Advanced Features

Icon Caching

Homarr caches icon lists for performance:
  • Repository lists: Cached for 24 hours
  • Icon images: Cached by browser
  • Local icons: Served with cache headers
  • Manual refresh: Available in settings

Icon Optimization

Automatic optimization for uploaded icons:
  • SVG minification (removes unnecessary data)
  • PNG compression (lossless)
  • WebP conversion (optional)
  • Thumbnail generation (for preview)

Icon Fallbacks

When icons fail to load:
  1. Show placeholder icon
  2. Display first letter of app name
  3. Use default icon for service type
  4. Show error indicator in edit mode

Next Steps

Creating Widgets

Use icons when creating widgets

Customize Boards

Apply consistent icon styling across boards

Widget Configuration

Some widgets support custom icons

Integrations

Icons for integration services

Build docs developers (and LLMs) love