Capacitor plugin to change the app icon at runtime.
- 🎨 Alternate icons: Switch the home-screen icon between the icons your app declares.
- 🔍 Current icon: Read the name of the icon that is currently in use.
- 🔄 Reset: Restore the default icon at any time.
- 🤝 Compatibility: Works alongside the App Shortcuts and Badge plugins.
- 📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 Up-to-date: Always supports the latest Capacitor version.
Missing a feature? Just open an issue and we'll take a look!
The App Icon plugin is typically used to personalize or refresh the app's appearance on the home screen, for example:
- Seasonal campaigns: Switch to a themed icon for events like Christmas and restore the default icon afterwards.
- Premium personalization: Let paying users choose their favorite icon from a set of alternate icons.
- In-app icon picker: Build a settings screen that lists all icons and highlights the one currently in use.
- Brand updates: Roll out a new logo as an alternate icon and switch to it at runtime.
| Plugin Version | Capacitor Version | Status |
|---|---|---|
| 0.x.x | >=8.x.x | Active support |
You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:
npx skills add capawesome-team/skills --skill capacitor-pluginsThen use the following prompt:
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-icon` plugin in my project.
If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
npm install @capawesome/capacitor-app-icon
npx cap syncThis plugin cannot add icons dynamically. Every icon you want to switch to must be declared by the app beforehand. The following sections describe how to declare alternate icons on each platform.
On Android, each alternate icon is declared as an <activity-alias> that points at the launcher activity. The plugin enables the requested alias and disables the others.
Open your AndroidManifest.xml and remove the launcher <intent-filter> from your .MainActivity. Then add one <activity-alias> for the default icon and one for each alternate icon. Exactly one alias must be android:enabled="true" (the default icon); all others must be android:enabled="false".
<!-- Remove the <intent-filter> from the MainActivity. -->
<activity
android:name=".MainActivity"
android:exported="true"
... />
<!-- The default icon (enabled). -->
<activity-alias
android:name=".AppIconDefault"
android:enabled="true"
android:exported="true"
android:icon="@mipmap/ic_launcher"
android:roundIcon="@mipmap/ic_launcher_round"
android:targetActivity=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity-alias>
<!-- An alternate icon (disabled). -->
<activity-alias
android:name=".Christmas"
android:enabled="false"
android:exported="true"
android:icon="@mipmap/ic_launcher_christmas"
android:roundIcon="@mipmap/ic_launcher_christmas_round"
android:targetActivity=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity-alias>
<!-- Another alternate icon (disabled). -->
<activity-alias
android:name=".Halloween"
android:enabled="false"
android:exported="true"
android:icon="@mipmap/ic_launcher_halloween"
android:roundIcon="@mipmap/ic_launcher_halloween_round"
android:targetActivity=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity-alias>The icon name passed to setIcon(...) is the alias name without the leading dot (e.g. Christmas). Add the referenced icon resources (e.g. @mipmap/ic_launcher_christmas) to your res/mipmap-* folders.
Note
The behavior after a change depends on the launcher. Some launchers apply the new icon only after the app's task is closed, and a few kill the app despite the plugin requesting otherwise. Shortcuts that were pinned to a now-disabled alias may stop working.
On iOS, alternate icons are declared as additional app icon sets in the asset catalog. Add one icon set per alternate icon (e.g. Christmas and Halloween) next to your primary AppIcon in Assets.xcassets and register the names (space-separated) in the build settings of your app target:
ASSETCATALOG_COMPILER_ALTERNATE_APPICON_NAMES = "Christmas Halloween";
ASSETCATALOG_COMPILER_INCLUDE_ALL_APPICON_ASSETS = YES;
In Xcode, these settings are called Alternate App Icon Sets and Include All App Icon Assets in the Asset Catalog Compiler section of the build settings.
The icon name passed to setIcon(...) is the name of the icon set (e.g. Christmas), case-sensitive. The primary icon (AppIcon) is restored with resetIcon(...).
Warning
Do not give an alternate icon set a name that starts with AppIcon (e.g. AppIconChristmas). In our testing on physical devices running iOS 26, alternate icons whose name shares the primary icon set's AppIcon prefix are not rendered on the home screen: setIcon(...) succeeds, but the system displays a blank placeholder icon instead of the alternate icon. The iOS Simulator is not affected, so make sure to test on a real device. This is an undocumented iOS behavior; using names without the AppIcon prefix is safe on all iOS versions.
Note
The system shows a user-visible alert every time the icon changes, and the icon cannot be changed while the app is in the background.
No configuration required for this plugin.
The following examples show how to check for alternate icon support, read the current icon, set an alternate icon, and reset to the default icon.
Use isAvailable() to check whether the current device supports alternate icons. On Android, this always resolves to true; on iOS, it resolves to the value of supportsAlternateIcons. Only available on Android and iOS:
import { AppIcon } from '@capawesome/capacitor-app-icon';
const isAvailable = async () => {
const { available } = await AppIcon.isAvailable();
return available;
};Read the name of the icon that is currently in use, for example to highlight it in an icon picker. Returns null if the default icon is in use. Only available on Android and iOS:
import { AppIcon } from '@capawesome/capacitor-app-icon';
const getCurrentIcon = async () => {
const { icon } = await AppIcon.getCurrentIcon();
return icon;
};Change the app icon to an alternate icon that your app has declared beforehand (see Installation). Only available on Android and iOS:
import { AppIcon } from '@capawesome/capacitor-app-icon';
const setIcon = async () => {
await AppIcon.setIcon({ icon: 'Christmas' });
};Restore the default app icon at any time. Only available on Android and iOS:
import { AppIcon } from '@capawesome/capacitor-app-icon';
const resetIcon = async () => {
await AppIcon.resetIcon();
};getCurrentIcon() => Promise<GetCurrentIconResult>Get the name of the icon that is currently in use.
Returns null if the default icon is in use.
Only available on Android and iOS.
Returns: Promise<GetCurrentIconResult>
Since: 0.1.0
isAvailable() => Promise<IsAvailableResult>Check if changing the app icon is supported on the current device.
On Android, this always resolves to true.
On iOS, this resolves to the value of supportsAlternateIcons.
Only available on Android and iOS.
Returns: Promise<IsAvailableResult>
Since: 0.1.0
resetIcon() => Promise<void>Restore the default app icon.
Only available on Android and iOS.
Since: 0.1.0
setIcon(options: SetIconOptions) => Promise<void>Change the app icon to the alternate icon with the given name.
The icon must be declared by the app beforehand. See the setup instructions for Android and iOS for more information.
Only available on Android and iOS.
| Param | Type |
|---|---|
options |
SetIconOptions |
Since: 0.1.0
| Prop | Type | Description | Since |
|---|---|---|---|
icon |
string | null |
The name of the icon that is currently in use. Returns null if the default icon is in use. |
0.1.0 |
| Prop | Type | Description | Since |
|---|---|---|---|
available |
boolean |
Whether or not changing the app icon is supported on the current device. | 0.1.0 |
| Prop | Type | Description | Since |
|---|---|---|---|
icon |
string |
The name of the alternate icon to use. On Android, this is the name of the <activity-alias> (without the leading dot). On iOS, this is the name of the alternate app icon set in the asset catalog. |
0.1.0 |
It changes the app icon at runtime on both Android and iOS through one fully typed API — switching to a declared alternate icon, reading the icon currently in use, resetting to the default, and checking whether the device supports alternate icons. It documents the platform realities honestly, from Android's launcher-dependent behavior to the system alert iOS shows on every change, so there are no surprises in production. The plugin is actively maintained against the latest Capacitor and OS versions.
No, this plugin cannot add icons dynamically. Every icon you want to switch to must be declared by the app beforehand, as an <activity-alias> in the AndroidManifest.xml on Android and as an alternate app icon set in the asset catalog on iOS. See the Installation section for detailed setup instructions.
On Android, it is the name of the <activity-alias> without the leading dot (e.g. Christmas). On iOS, it is the name of the alternate app icon set in the asset catalog.
The behavior after a change depends on the launcher. Some launchers apply the new icon only after the app's task is closed, and a few even kill the app despite the plugin requesting otherwise. Also note that shortcuts pinned to a now-disabled alias may stop working.
The system shows a user-visible alert every time the icon changes. This is standard iOS behavior and cannot be suppressed. Also note that the icon cannot be changed while the app is in the background.
Call isAvailable() before offering an icon picker. On Android, it always resolves to true. On iOS, it resolves to the value of supportsAlternateIcons.
Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.
- App Shortcuts: Manage app shortcuts and quick actions on the home screen.
- App Update: Assist your users with native app updates.
- Badge: Access and update the badge number of the app icon.
Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.
See CHANGELOG.md.
See LICENSE.