Icon Switcher

A Flutter plugin to dynamically change your app icon at runtime. Supports iOS, Android, Web, macOS, Windows, and Linux.

Migrating from mobile_icon_switcher? See the Migration Guide at the bottom.

Platform Support

Installation

dependencies:
  basic_icon_switcher: ^1.0.0

Quick Start

import 'package:basic_icon_switcher/basic_icon_switcher.dart';

// Switch to an alternate icon
await IconSwitcher.changeIcon(
  iconName: 'dark',
  androidActivityAlias: 'com.example.myapp.Dark', // Android only
  webFaviconUrl: 'icons/dark.png',                // Web only
  desktopIconAsset: 'assets/icons/dark.png',       // macOS/Windows/Linux
);

// Reset to default
await IconSwitcher.resetIcon();

// Check current icon (iOS/Android)
final current = await IconSwitcher.getCurrentIcon(); // null = default

// Check if supported
final supported = await IconSwitcher.isSupported;

Platform Setup

iOS

<key>CFBundleIcons</key>
<dict>
    <key>CFBundleAlternateIcons</key>
    <dict>
        <key>dark</key>
        <dict>
            <key>UIPrerenderedIcon</key>
            <false/>
            <key>CFBundleIconFiles</key>
            <array>
                <string>dark</string>
            </array>
        </dict>
        <key>light</key>
        <dict>
            <key>UIPrerenderedIcon</key>
            <false/>
            <key>CFBundleIconFiles</key>
            <array>
                <string>light</string>
            </array>
        </dict>
    </dict>
</dict>

await IconSwitcher.changeIcon(iconName: 'dark');

Android

<activity-alias
    android:name=".Dark"
    android:targetActivity=".MainActivity"
    android:icon="@mipmap/dark"
    android:enabled="false">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity-alias>

package com.example.myapp

import io.flutter.embedding.android.FlutterActivity

class MainActivity: FlutterActivity()
class Dark: FlutterActivity()

await IconSwitcher.changeIcon(
  iconName: 'dark',
  androidActivityAlias: 'com.example.myapp.Dark',
);

Web

<link rel="icon" type="image/png" href="favicon.png" />

await IconSwitcher.changeIcon(
  iconName: 'dark',
  webFaviconUrl: 'icons/dark.png',
);

macOS

flutter:
  assets:
    - assets/icons/

await IconSwitcher.changeIcon(
  iconName: 'dark',
  desktopIconAsset: 'assets/icons/dark.png',
);

Windows

await IconSwitcher.changeIcon(
  iconName: 'dark',
  desktopIconAsset: 'assets/icons/dark.png',
);

Linux

await IconSwitcher.changeIcon(
  iconName: 'dark',
  desktopIconAsset: 'assets/icons/dark.png',
);

API Reference

IconSwitcher.changeIcon()

static Future<bool> changeIcon({
  required String iconName,
  String? androidActivityAlias,
  String? webFaviconUrl,
  String? desktopIconAsset,
})

IconSwitcher.resetIcon()

Resets to the default icon on all platforms.

IconSwitcher.getCurrentIcon()

Returns the current icon name, or null if the default is active. Currently supported on iOS and Android only.

IconSwitcher.isSupported

Returns true if icon switching is supported on the current platform.

Platform Limitations

Migration from mobile_icon_switcher

Breaking Changes

1. Package name: mobile_icon_switcher → basic_icon_switcher
2. Class name: MobileIconSwitcher → IconSwitcher
3. setDefaultComponent() removed: No longer needed — the Android plugin auto-detects the default component.
4. changeIcon() signature changed: Now uses named parameters.
5. platformVersion removed: Use Flutter's built-in platform detection instead.

Before (mobile_icon_switcher)

import 'package:mobile_icon_switcher/mobile_icon_switcher.dart';

// Required on Android
MobileIconSwitcher.setDefaultComponent("com.example.app.MainActivity");

// Change icon
await MobileIconSwitcher.changeIcon('dark', 'com.example.app.Dark');

// Reset
await MobileIconSwitcher.resetIcon();

After (basic_icon_switcher)

import 'package:basic_icon_switcher/basic_icon_switcher.dart';

// Change icon (no setDefaultComponent needed!)
await IconSwitcher.changeIcon(
  iconName: 'dark',
  androidActivityAlias: 'com.example.app.Dark',
);

// Reset
await IconSwitcher.resetIcon();

The first argument here is the IconName, this part is necessary for IOS mostly, the second argument is the Activity with the ApplicationId of Android.

Reseting the Apps Icon to default

To revert the app icon to its default after you have completed the iOS and/or Android Setup mentioned above, you can simply call this method:

await MobileIconSwitcher.resetIcon();

This method doesn’t require any arguments. Calling this will reset the app icon to the default one set in your project, whether you’re on iOS or Android. Remember to handle any possible errors that might occur while resetting, ensuring a smooth user experience.

Note: For IOS there is a real option to reset the App's icon for Android, there isn't therefore I will just set the Default Component as the "new" App Icon.

Note

Please be aware that the Android solution is as stated before not the best solution but however it works, for me it takes a bit until Android updates the App on the Homescreen so pressing on an Icon and getting the message Unknown App or something like this can happen! It takes a few moments and than the App is again back with the new Icon and can be started without any issues.