@howincodes/expo-dynamic-app-icon

Easily change your app icon dynamically in Expo SDK 53+!

What's New in v3:

• Expo SDK 53/54/55 support
• Android crash fix — no more unexpected app closures after icon change
• setAppIcon(null) fix — resetting to default now works correctly on Android
• Proper error handling — setAppIcon now returns false when it actually fails
• setAppIcon is now async — returns a Promise
• Thread-safe Android — no more race conditions on rapid icon changes
• Image path validation — clear errors when icon files are missing
• Deep link preservation — activity aliases now inherit all intent filters
• iOS private API fallback — gracefully falls back to public API if private API unavailable

Features:

• Reset icon to default
• Support for round icons
• Different icons for iOS and Android
• Dynamic icon variants for iOS (light, dark, tinted)
• iOS icon update with or without alert popup
• Simple API to get and set the app icon
• Android icon change without app restart

Demo

Installation

npx expo install @howincodes/expo-dynamic-app-icon

Setup

Add the plugin to your app.json:

"plugins": [
  [
    "@howincodes/expo-dynamic-app-icon",
    {
      "defaultLight": {
        "ios": "./assets/ios_icon_light.png",
        "android": {
          "foregroundImage": "./assets/android_icon_light_fg.png",
          "backgroundColor": "#FFFFFF"
        }
      },
      "defaultDark": {
        "ios": "./assets/ios_icon_dark.png",
        "android": {
          "foregroundImage": "./assets/android_icon_dark_fg.png",
          "backgroundColor": "#121212"
        }
      },
      "legacyRed": {
        "ios": "./assets/ios_icon_red.png",
        "android": "./assets/android_icon_red_legacy.png"
      },
      "dynamicTheme": {
        "ios": {
          "light": "./assets/ios_icon_themed_light.png",
          "dark": "./assets/ios_icon_themed_dark.png",
          "tinted": "./assets/ios_icon_themed_tinted.png"
        }
      }
    }
  ]
]

Note on Android Adaptive Icons: For Android, you can provide an object with foregroundImage (path to your foreground asset) and backgroundColor (hex string) to generate proper adaptive icons. If you provide a direct string path, it will be treated as a legacy icon.

Android Setup

Run the following command:

expo prebuild

Then, check if the following lines have been added to AndroidManifest.xml. The android:icon and android:roundIcon attributes will point to different resources based on your configuration:

For Adaptive Icons (example: defaultDark):

<activity-alias
  android:name="expo.modules.dynamicappicon.example.MainActivitydefaultDark"
  android:enabled="false"
  android:exported="true"
  android:icon="@mipmap/ic_launcher_adaptive_defaultdark"
  android:roundIcon="@mipmap/ic_launcher_adaptive_defaultdark"
  android:targetActivity=".MainActivity">
  <intent-filter>
    <action android:name="android.intent.action.MAIN"/>
    <category android:name="android.intent.category.LAUNCHER"/>
  </intent-filter>
</activity-alias>

For Legacy Icons (example: legacyRed):

<activity-alias
  android:name="expo.modules.dynamicappicon.example.MainActivitylegacyRed"
  android:enabled="false"
  android:exported="true"
  android:icon="@mipmap/legacyred"
  android:roundIcon="@mipmap/legacyred_round"
  android:targetActivity=".MainActivity">
  <intent-filter>
    <action android:name="android.intent.action.MAIN"/>
    <category android:name="android.intent.category.LAUNCHER"/>
  </intent-filter>
</activity-alias>

Usage

Set App Icon

import { setAppIcon } from "@howincodes/expo-dynamic-app-icon";

// Change app icon to 'red' (returns a Promise in v3)
const result = await setAppIcon("red");

// Reset to default icon
await setAppIcon(null);

Parameters:

setAppIcon(
  name: IconName | null,
  isInBackground?: boolean
): Promise<IconName | "DEFAULT" | false>

| Parameter | Type | Default | Description | | ---------------- | ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------ | | name | IconName \| null | null | The icon name to switch to. Pass null to reset to the default icon. | | isInBackground | boolean | true | - true: Icon changes silently in the background (no alert on iOS).- false: Immediate change, with system alert on iOS. |

Returns (Promise):

• "DEFAULT" if reset to the original icon.
• The new icon name on success.
• false if an error occurs.

Get Current Icon

import { getAppIcon } from "@howincodes/expo-dynamic-app-icon";

// Get the current app icon name (async in v3)
const icon = await getAppIcon();
console.log(icon); // "red" (or "DEFAULT" if not changed)

Platform Behavior:

• iOS: await setAppIcon("dark") resolves after the icon change completes (or fails). The return value accurately reflects success/failure.
• Android: await setAppIcon("dark") resolves immediately after queuing the change. The actual icon switch happens when the app enters the background. This means the promise always resolves with the icon name, even if the change hasn't been applied yet.

Notes:

• Android limitations: Android does not support icon changes while the app is running in the foreground. To work around this, the icon is changed when the app enters the Pause state (background).

• Pause state can also trigger during events like permission dialogs. To avoid unwanted icon changes, a 5-second delay is added to ensure the app is truly in the background.

• To disable the delay and apply the icon change immediately (with the risk of it running during permission dialogs or other pause events), set:

  await setAppIcon("red", false);

  • On iOS, isInBackground: false triggers the system alert immediately.
  • On Android, it applies the icon change right away without waiting.

Migration from v2 to v3

Breaking Changes:

1. setAppIcon and getAppIcon are now async — wrap calls with await:

   // v2
   const result = setAppIcon("dark");
   const icon = getAppIcon();
   
   // v3
   const result = await setAppIcon("dark");
   const icon = await getAppIcon();

2. Minimum Expo SDK is now 53 — update your project if on SDK 52 or below.

3. Error handling improved — setAppIcon now returns false when the icon change actually fails (previously it returned the icon name even on failure).

Support the Original Author

A huge shoutout to outsung for the original package!

If you find this useful, consider buying him a coffee:

About Us

This package is maintained by HowinCloud – delivering powerful cloud-based solutions for modern app development.