Electron has democratized desktop application development by allowing web developers to build for Windows, macOS, and Linux using the technologies they already know — HTML, CSS, and JavaScript. But with great accessibility comes great responsibility, particularly when it comes to icons. Electron applications must provide correctly formatted icons for each operating system, and the format requirements differ dramatically between platforms in ways that catch many developers off guard.
A common Electron mistake: shipping the same PNG file as the icon for all three platforms. It will technically work on some platforms, but it will look suboptimal on Windows (which expects ICO format) and will not take advantage of the multi-resolution capabilities that macOS's ICNS format provides for Retina displays. Professional Electron apps provide platform-specific icon formats.
Windows: The ICO Format
Windows expects application icons in .ico format. Unlike PNG, an ICO file is a container format that holds multiple images at different resolutions within a single file. A proper Windows ICO for a modern Electron app should contain at minimum: 16×16, 32×32, 48×48, 64×64, 128×128, and 256×256 pixel variants. Windows selects the most appropriate size depending on display context — taskbar, file manager, application switcher, and so on.
The ICO format also supports different color depths. While modern Windows uses 32-bit color with alpha transparency, older compatibility modes may request 8-bit or even 4-bit variants. For maximum compatibility, a well-prepared ICO file should include all standard sizes. Building this manually requires dedicated ICO editors — unless you use a generation tool that handles it automatically.
macOS: The ICNS Format
macOS uses the proprietary .icns format, which is conceptually similar to ICO but tailored for Apple's ecosystem. A proper macOS ICNS file for an Electron app should contain sizes ranging from 16×16 to 1024×1024, including @2x Retina variants for each size. The naming convention within the ICNS container follows Apple's own specification and cannot be arbitrary.
🪟 Windows
Requires .ico format containing multiple embedded sizes from 16×16 to 256×256 for taskbar, explorer, and UI contexts.
🍎 macOS
Requires .icns format with standard and @2x Retina variants from 16×16 to 1024×1024 for Retina-quality display.
🐧 Linux
Uses PNG format, typically at 512×512 or 256×256, following freedesktop.org icon theme specifications.
The Electron Build Configuration
When building an Electron app with electron-builder or electron-forge, you specify icons in your build configuration. The build tool reads from a dedicated icons directory or explicitly specified icon paths. Getting this configuration right — pointing to the correct icon file for each platform — requires understanding both the build tool's expectations and the OS icon format requirements.
Iconify generates Electron-ready icon assets with the correct folder structure and naming conventions that electron-builder expects, making the entire integration seamless. See all supported platforms at iconify.roboticela.com.
Electron Icons for All Three Platforms
ICO for Windows. ICNS for Mac. PNG for Linux. One tool. Done.
Top comments (0)