App Icon

The App Icon is the icon players see on their home screen once they've installed your app. This page walks you through replacing the default icon with your own — in one drag-and-drop, for both Android and iOS at every size the stores require.

What you need

• A single square PNG image, at least 1024×1024 pixels.
• Solid background — avoid transparency. Apple rejects App Store icons with a transparent alpha channel, so keep the whole square filled.
• Non-square images will be stretched to a square canvas — crop your source image first if that matters.

You don't need to prepare multiple sizes yourself. The Setup Page generates every required size for you.

Step 1 — Open the App Icon page

Open the Setup Page in your browser and go to the App Icon section in the sidebar.

You'll see two cards:

• Current icon — a preview of the icon that's currently in your project. On a fresh setup, this shows the demo app's icon.
• Upload new icon — a drop zone where you replace the icon.

Step 2 — Upload your icon

Drop your 1024×1024 PNG onto the upload zone (or click it to open a file picker).

As soon as the file is loaded, the Setup Page automatically:

1. Resizes it to every Android launcher-icon density (5 sizes, from mdpi to xxxhdpi).
2. Resizes it to every iOS App Icon size (about 10 different sizes covering iPhone, iPad, and the App Store).
3. Also writes a 512×512 copy for the in-app "About" screen logo.

You'll see a live list showing each file as it's written, with a checkmark next to every success. When it's done, the preview at the top updates to show your new icon.

Step 3 — Rebuild the app

Icon changes only appear after the app is rebuilt. Follow the usual sync + run steps:

make sync

Then run the app on your phone or emulator (see Publishing → Build & Publish) — the new icon will appear on the home screen.

Design tips

• Keep the meaningful part of your icon inside the middle 80% of the canvas. Android launchers and iOS home screen shapes crop the outer edges to different shapes (circle, rounded square, squircle, …), so anything near the border may be cut off.
• Use bold, simple shapes — the icon is often shown at 48×48 pixels or smaller. Fine details won't be readable.

• Consider the app icon at both light and dark backgrounds — most users will see it on a variety of wallpapers.
• On Android 13+, users can opt into themed icons that adapt to their wallpaper's colours. If you want to support this, you can ship a monochrome variant (advanced — not covered by the Setup Page).

Common problems

• "The upload wrote fewer files than expected" — hover over any row marked with a red ✕ to see the exact error. This is usually a permissions issue if you moved the project or opened it from a synced folder like iCloud or Dropbox.
• "New icon doesn't show up on my phone" — you haven't rebuilt the app yet. On Android and iOS, the home screen icon is baked in at build time — it won't change until you re-install the app with a fresh build.
• "App Store rejects my icon" — usually because of transparency in the source image. Re-export the PNG with a solid background and try again.