App Icon

The packaged application icon is the image Finder, the Dock, the Windows taskbar, Start Menu, and Linux desktop launchers show for your app. Put a PNG at resources/icon.png. You can also change a window icon or the macOS Dock icon while the app is running.

#Source icon

Add a square PNG that is at least 256×256 pixels at resources/icon.png. 1024×1024 is a good source. quickgui build resizes it to every size macOS, Windows, and Linux need.

my-app/
├── resources/
│   └── icon.png
├── src/main.rs
└── quickgui.config.ts

The CLI writes .icns for macOS, .ico for the Windows installer, and the Freedesktop hicolor sizes for Linux. Development reloads skip generated containers; production builds and a configured macos.icon still install an icon.

Optional resources/icon.iconset/icon_<n>x<n>.png files replace a generated size with a hand-drawn one. That folder is a build input and is not copied into the packaged app.

Set icon in the CLI config only when the source PNG lives somewhere other than resources/icon.png.

#Platform-specific icons

Use these when you already have a platform container:

resources/icon.png
resources/icon.icns
resources/icon.ico

resources/icon.icns is used on macOS when macos.icon is omitted. resources/icon.ico is used by the NSIS installer when windows.icon is omitted. linux.icon is a square PNG used when both resources/icon.png and icon are omitted.

export default defineConfig({
  language: "rust",
  name: "My App",
  identifier: "com.example.my-app",
  entry: ".",
  macos: { icon: "packaging/AppIcon.icns" },
  windows: { icon: "packaging/AppIcon.ico" },
});

macos.icon must be an .icns. windows.icon is an .ico. These config paths override the files in resources/.

Document-type icons are a basename inside the packaged resources. See Bundled Resources.

#Window and Dock icons

The packaged icon is the application identity. A window can show a different image on Windows and X11:

let icon = Image::open(
    cx.app_paths()
        .unwrap()
        .resource_dir()
        .join("icon.png"),
)
.expect("icon");
cx.open_window(WindowOptions::new("My App").icon(icon), App);

After the window exists, cx.set_window_icon(icon) and cx.clear_window_icon() update that image. On macOS, windows do not have their own icon. Use cx.set_dock_icon(icon) to replace the Dock image for this process.

Menu-bar and notification-area icons are a different image. See Tray Icon.

#Generated sizes

Every listed size is generated from the source PNG. The source must be square, at least 256×256, and at most 16 MiB.