Icon Picker
The icon picker provides an intuitive interface for selecting icons:Opening the Icon Picker
Icon Repositories
Homarr sources icons from multiple high-quality repositories:Repository Details
Dashboard Icons (Recommended)
Dashboard Icons (Recommended)
Description: Curated collection of icons specifically for dashboard applications and self-hosted services.Size: 1,000+ iconsStyle: Modern, flat design with consistent sizingBest for: Apps like Plex, Sonarr, Radarr, Jellyfin, Home Assistant, and other popular self-hosted servicesLicense: Free to useFormat: SVG and PNGExample icons: Plex, Sonarr, Radarr, qBittorrent, Jellyfin, Nextcloud, Portainer, Proxmox
selfh.st Icons
selfh.st Icons
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
SimpleIcons
SimpleIcons
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
Papirus
Papirus
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
Homelab SVG Assets
Homelab SVG Assets
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
Local Icons
Local Icons
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:Basic Search
Type in the search box to filter icons by name:Auto Icon Search
Homarr can automatically suggest icons based on app name:- Fuzzy matching for typos
- Synonym support (“jelly” matches “jellyfin”)
- Multi-word handling
- Priority ranking (exact matches first)
Repository Filtering
Filter icons by repository:- Open icon picker
- Click Filter by Repository
- Select one or more repositories
- Only icons from selected repositories will show
Custom Icon URLs
Use any image URL as an icon:Using Custom URLs
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
- Modern format
- Small file size
- Good quality
- No transparency
- Small file size
- Lower quality
- 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
Uploading Local Icons
Upload custom icons directly to Homarr:Upload Process
Select Files
Click Upload Icons and select one or more image files.Supported formats: SVG, PNG, JPG, WebP
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)
- 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
- 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
- Direct access to GitHub repositories
- Automatic updates when repository changes
- Version pinning support
- Free CDN via jsDelivr
jsDelivr Repository
- Fast CDN delivery
- Supports npm packages
- Automatic caching
- High availability
Local Repository
- Full control over icons
- No external dependencies
- Custom icons not available elsewhere
- Private/internal branding
Troubleshooting
Icon not loading
Icon not loading
Check:
- Icon URL is accessible
- CORS allows loading from Homarr domain
- Image file exists and is valid
- Network connectivity
- Test URL in browser directly
- Use CDN URLs instead of direct links
- Upload icon locally
- Check browser console for errors
Icon picker showing no icons
Icon picker showing no icons
Check:
- Internet connectivity (for external repositories)
- Icon repositories are configured
- No network/firewall blocking requests
- Cache not corrupted
- Check network connectivity
- Clear icon cache in settings
- Restart Homarr
- Check server logs
Icons look blurry
Icons look blurry
Check:
- Icon resolution is adequate (minimum 128x128)
- SVG preferred over raster
- Browser zoom level
- Display scaling
- Use SVG format
- Upload higher resolution icon
- Use icons from Dashboard Icons repository
- Test at 100% zoom
Cannot upload icon
Cannot upload icon
Check:
- File format is supported (SVG, PNG, JPG, WebP)
- File size under limit
- Storage space available
- Sufficient permissions
- 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:- Show placeholder icon
- Display first letter of app name
- Use default icon for service type
- 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
