--- description: Capacitor plugin to change the app icon at runtime on Android and iOS. Switch between alternate icons, read the current icon, and reset to the default. title: Capacitor App Icon Plugin for Android & iOS - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/app-icon.png --- [Skip to content ](#capacitor-app-icon-plugin) [πŸ“² Introducing **Build Sharing** β€” get your builds onto testers' devices with a link & QR code. No account required. ](/blog/share-mobile-app-builds-with-testers/) * [ SDKs ](/docs/sdks/) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ License ](#license) * [ App Integrity ](/docs/sdks/capacitor/app-integrity/) * [ App Language ](/docs/sdks/capacitor/app-language/) * [ App Launcher ](/docs/sdks/capacitor/app-launcher/) * [ App Review ](/docs/sdks/capacitor/app-review/) * [ App Shortcuts ](/docs/sdks/capacitor/app-shortcuts/) * [ App Tracking Transparency ](/docs/sdks/capacitor/app-tracking-transparency/) * [ App Update ](/docs/sdks/capacitor/app-update/) * [ Apple Sign-In ](/docs/sdks/capacitor/apple-sign-in/) * [ Asset Manager ](/docs/sdks/capacitor/asset-manager/) * [ Audio Player ](/docs/sdks/capacitor/audio-player/) * [ Audio Recorder ](/docs/sdks/capacitor/audio-recorder/) * [ Audio Session ](/docs/sdks/capacitor/audio-session/) * [ Background Task ](/docs/sdks/capacitor/background-task/) * [ Badge ](/docs/sdks/capacitor/badge/) * [ Barometer ](/docs/sdks/capacitor/barometer/) * [ Battery ](/docs/sdks/capacitor/battery/) * [ Biometrics ](/docs/sdks/capacitor/biometrics/) * [ Bluetooth Low Energy ](/docs/sdks/capacitor/bluetooth-low-energy/) * [ Clipboard ](/docs/sdks/capacitor/clipboard/) * [ Cloudinary ](/docs/sdks/capacitor/cloudinary/) * [ Compass ](/docs/sdks/capacitor/compass/) * [ Contacts ](/docs/sdks/capacitor/contacts/) * [ Datetime Picker ](/docs/sdks/capacitor/datetime-picker/) * [ Device Info ](/docs/sdks/capacitor/device-info/) * [ Dialog ](/docs/sdks/capacitor/dialog/) * [ Exif ](/docs/sdks/capacitor/exif/) * [ Facebook Sign-In ](/docs/sdks/capacitor/facebook-sign-in/) * [ File Compressor ](/docs/sdks/capacitor/file-compressor/) * [ File Opener ](/docs/sdks/capacitor/file-opener/) * [ File Picker ](/docs/sdks/capacitor/file-picker/) * [ Firebase ](/docs/sdks/capacitor/firebase/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ License ](#license) # Capacitor App Icon Plugin[ΒΆ](#capacitor-app-icon-plugin "Permanent link") Capacitor plugin to change the app icon at runtime. [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) ## Features[ΒΆ](#features "Permanent link") * 🎨 **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. * πŸ“¦ **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](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases[ΒΆ](#use-cases "Permanent link") 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[ΒΆ](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | \>=8.x.x | Active support | ## Installation[ΒΆ](#installation "Permanent link") You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: `[](#%5F%5Fcodelineno-0-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-1-1) 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: `[](#%5F%5Fcodelineno-2-1)npm install @capawesome/capacitor-app-icon [](#%5F%5Fcodelineno-2-2)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[ΒΆ](#android "Permanent link") On Android, each alternate icon is declared as an [](https://developer.android.com/guide/topics/manifest/activity-alias-element) that points at the launcher activity. The plugin enables the requested alias and disables the others. Open your `AndroidManifest.xml` and remove the launcher `` from your `.MainActivity`. Then add one `` 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"`. `[](#%5F%5Fcodelineno-3-1) [](#%5F%5Fcodelineno-3-2) [](#%5F%5Fcodelineno-3-6) [](#%5F%5Fcodelineno-3-7) [](#%5F%5Fcodelineno-3-8) [](#%5F%5Fcodelineno-3-15) [](#%5F%5Fcodelineno-3-16) [](#%5F%5Fcodelineno-3-17) [](#%5F%5Fcodelineno-3-18) [](#%5F%5Fcodelineno-3-19) [](#%5F%5Fcodelineno-3-20) [](#%5F%5Fcodelineno-3-21) [](#%5F%5Fcodelineno-3-22) [](#%5F%5Fcodelineno-3-29) [](#%5F%5Fcodelineno-3-30) [](#%5F%5Fcodelineno-3-31) [](#%5F%5Fcodelineno-3-32) [](#%5F%5Fcodelineno-3-33) [](#%5F%5Fcodelineno-3-34) [](#%5F%5Fcodelineno-3-35) [](#%5F%5Fcodelineno-3-36) [](#%5F%5Fcodelineno-3-43) [](#%5F%5Fcodelineno-3-44) [](#%5F%5Fcodelineno-3-45) [](#%5F%5Fcodelineno-3-46) [](#%5F%5Fcodelineno-3-47) ` 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[ΒΆ](#ios "Permanent link") 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: `[](#%5F%5Fcodelineno-4-1)ASSETCATALOG_COMPILER_ALTERNATE_APPICON_NAMES = "Christmas Halloween"; [](#%5F%5Fcodelineno-4-2)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[ΒΆ](#configuration "Permanent link") No configuration required for this plugin. ## Usage[ΒΆ](#usage "Permanent link") 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[ΒΆ](#check-if-changing-the-app-icon-is-supported "Permanent link") 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: `[](#%5F%5Fcodelineno-5-1)import { AppIcon } from '@capawesome/capacitor-app-icon'; [](#%5F%5Fcodelineno-5-2) [](#%5F%5Fcodelineno-5-3)const isAvailable = async () => { [](#%5F%5Fcodelineno-5-4) const { available } = await AppIcon.isAvailable(); [](#%5F%5Fcodelineno-5-5) return available; [](#%5F%5Fcodelineno-5-6)}; ` ### Get the current icon[ΒΆ](#get-the-current-icon "Permanent link") 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: `[](#%5F%5Fcodelineno-6-1)import { AppIcon } from '@capawesome/capacitor-app-icon'; [](#%5F%5Fcodelineno-6-2) [](#%5F%5Fcodelineno-6-3)const getCurrentIcon = async () => { [](#%5F%5Fcodelineno-6-4) const { icon } = await AppIcon.getCurrentIcon(); [](#%5F%5Fcodelineno-6-5) return icon; [](#%5F%5Fcodelineno-6-6)}; ` ### Set an alternate icon[ΒΆ](#set-an-alternate-icon "Permanent link") Change the app icon to an alternate icon that your app has declared beforehand (see [Installation](#installation)). Only available on Android and iOS: `[](#%5F%5Fcodelineno-7-1)import { AppIcon } from '@capawesome/capacitor-app-icon'; [](#%5F%5Fcodelineno-7-2) [](#%5F%5Fcodelineno-7-3)const setIcon = async () => { [](#%5F%5Fcodelineno-7-4) await AppIcon.setIcon({ icon: 'Christmas' }); [](#%5F%5Fcodelineno-7-5)}; ` ### Reset to the default icon[ΒΆ](#reset-to-the-default-icon "Permanent link") Restore the default app icon at any time. Only available on Android and iOS: `[](#%5F%5Fcodelineno-8-1)import { AppIcon } from '@capawesome/capacitor-app-icon'; [](#%5F%5Fcodelineno-8-2) [](#%5F%5Fcodelineno-8-3)const resetIcon = async () => { [](#%5F%5Fcodelineno-8-4) await AppIcon.resetIcon(); [](#%5F%5Fcodelineno-8-5)}; ` ## API[ΒΆ](#api "Permanent link") * [getCurrentIcon()](#getcurrenticon) * [isAvailable()](#isavailable) * [resetIcon()](#reseticon) * [setIcon(...)](#seticon) * [Interfaces](#interfaces) ### getCurrentIcon()[ΒΆ](#getcurrenticon "Permanent link") `[](#%5F%5Fcodelineno-9-1)getCurrentIcon() => Promise ` 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](#getcurrenticonresult)>` **Since:** 0.1.0 --- ### isAvailable()[ΒΆ](#isavailable "Permanent link") `[](#%5F%5Fcodelineno-10-1)isAvailable() => Promise ` 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](#isavailableresult)>` **Since:** 0.1.0 --- ### resetIcon()[ΒΆ](#reseticon "Permanent link") `[](#%5F%5Fcodelineno-11-1)resetIcon() => Promise ` Restore the default app icon. Only available on Android and iOS. **Since:** 0.1.0 --- ### setIcon(...)[ΒΆ](#seticon "Permanent link") `[](#%5F%5Fcodelineno-12-1)setIcon(options: SetIconOptions) => Promise ` 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](https://capawesome.io/docs/sdks/capacitor/app-icon/#android) and [iOS](https://capawesome.io/docs/sdks/capacitor/app-icon/#ios) for more information. Only available on Android and iOS. | Param | Type | | ----------- | --------------------------------- | | **options** | [SetIconOptions](#seticonoptions) | **Since:** 0.1.0 --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### GetCurrentIconResult[ΒΆ](#getcurrenticonresult "Permanent link") | 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 | #### IsAvailableResult[ΒΆ](#isavailableresult "Permanent link") | Prop | Type | Description | Since | | ------------- | ------- | ------------------------------------------------------------------------ | ----- | | **available** | boolean | Whether or not changing the app icon is supported on the current device. | 0.1.0 | #### SetIconOptions[ΒΆ](#seticonoptions "Permanent link") | 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 | ## FAQ[ΒΆ](#faq "Permanent link") ### How is this plugin different from other similar plugins?[ΒΆ](#how-is-this-plugin-different-from-other-similar-plugins "Permanent link") 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?[ΒΆ](#can-i-add-new-app-icons-at-runtime "Permanent link") No, this plugin cannot add icons dynamically. Every icon you want to switch to must be declared by the app beforehand, as an `` in the `AndroidManifest.xml` on Android and as an alternate app icon set in the asset catalog on iOS. See the [Installation](#installation) section for detailed setup instructions. ### What icon name do I pass to `setIcon`?[ΒΆ](#what-icon-name-do-i-pass-to-seticon "Permanent link") On Android, it is the name of the `` 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?[ΒΆ](#why-is-the-new-icon-not-applied-immediately-on-android "Permanent link") 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?[ΒΆ](#why-does-ios-show-an-alert-when-the-icon-changes "Permanent link") 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?[ΒΆ](#how-do-i-know-if-the-device-supports-alternate-icons "Permanent link") 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?[ΒΆ](#can-i-use-this-plugin-with-ionic-react-vue-or-angular "Permanent link") 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[ΒΆ](#related-plugins "Permanent link") * [App Shortcuts](https://capawesome.io/docs/sdks/capacitor/app-shortcuts/): Manage app shortcuts and quick actions on the home screen. * [Badge](https://capawesome.io/docs/sdks/capacitor/badge/): Access and update the badge number of the app icon. * [App Update](https://capawesome.io/docs/sdks/capacitor/app-update/): Assist your users with native app updates. ## Newsletter[ΒΆ](#newsletter "Permanent link") Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog[ΒΆ](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-icon/CHANGELOG.md). ## License[ΒΆ](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-icon/LICENSE). July 8, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/app-icon/#article", "headline": "Capacitor App Icon Plugin for Android & iOS", "name": "Capacitor App Icon Plugin for Android & iOS", "description": "Capacitor plugin to change the app icon at runtime on Android and iOS. Switch between alternate icons, read the current icon, and reset to the default.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/app-icon/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/app-icon/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/app-icon/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/app-icon/#software", "name": "Capacitor App Icon Plugin for Android & iOS", "description": "Capacitor plugin to change the app icon at runtime on Android and iOS. Switch between alternate icons, read the current icon, and reset to the default.", "url": "https://capawesome.io/docs/sdks/capacitor/app-icon/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]} {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "How is this plugin different from other similar plugins?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "Can I add new app icons at runtime?", "acceptedAnswer": {"@type": "Answer", "text": "No, this plugin cannot add icons dynamically. Every icon you want to switch to must be declared by the app beforehand, as an 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."}}, {"@type": "Question", "name": "What icon name do I pass to setIcon?", "acceptedAnswer": {"@type": "Answer", "text": "On Android, it is the name of the without the leading dot (e.g. Christmas). On iOS, it is the name of the alternate app icon set in the asset catalog."}}, {"@type": "Question", "name": "Why is the new icon not applied immediately on Android?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "Why does iOS show an alert when the icon changes?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "How do I know if the device supports alternate icons?", "acceptedAnswer": {"@type": "Answer", "text": "Call isAvailable() before offering an icon picker. On Android, it always resolves to true. On iOS, it resolves to the value of supportsAlternateIcons."}}, {"@type": "Question", "name": "Can I use this plugin with Ionic, React, Vue or Angular?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}], "url": "https://capawesome.io/docs/sdks/capacitor/app-icon/"} ```