Capacitor App Icon Plugin

Capacitor plugin to change the app icon at runtime.

Features

• 🎨 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!

Use Cases

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.

Compatibility

Installation

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-plugins

Then 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 sync

This 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.

Android

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.

iOS

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.

Configuration

No configuration required for this plugin.

Usage

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.

Check if changing the app icon is supported

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;
};

Get the current icon

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;
};

Set an alternate 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' });
};

Reset to the default icon

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();
};

API

• getCurrentIcon()
• isAvailable()
• resetIcon()
• setIcon(...)
• Interfaces

getCurrentIcon()

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()

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()

resetIcon() => Promise<void>

Restore the default app icon.

Only available on Android and iOS.

Since: 0.1.0

setIcon(...)

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.

Since: 0.1.0

Interfaces

GetCurrentIconResult

IsAvailableResult

SetIconOptions

FAQ

How is this plugin different from other similar plugins?

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.

Can I add new app icons at runtime?

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.

What icon name do I pass to setIcon?

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.

Why is the new icon not applied immediately on Android?

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.

Why does iOS show an alert when the icon changes?

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.

How do I know if the device supports alternate icons?

Call isAvailable() before offering an icon picker. On Android, it always resolves to true. On iOS, it resolves to the value of supportsAlternateIcons.

Can I use this plugin with Ionic, React, Vue or Angular?

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.

Related Plugins

• 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.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.