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
├── app.tsx
└── 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: "typescript",
  name: "My App",
  identifier: "com.example.my-app",
  entry: "app.tsx",
  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:

import { Window } from "@quickgui/native";
import { createRenderer } from "@quickgui/solid";

new Window({
  title: "My App",
  icon: iconPath,
  renderer: createRenderer(App),
});

iconPath is an absolute filesystem path. Join it from app.getPaths() as shown in Bundled Resources. After the window exists, call window.setIcon(iconPath) or window.clearIcon().

On macOS, windows do not have their own icon. Use app.dock.setIcon(iconPath) 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.