dynamic_icon_plus 0.1.0

Modern Flutter plugin for dynamically changing app launcher icons at runtime on Android and iOS without restarting the application.

🇺🇿 O'zbekcha Hujjatlar  •  🇬🇧 English Documentation

🎭 DynamicIconPlus — Dynamic App Launcher Icon Switching for Flutter

---

🤖 Android

🍎 iOS

---

A modern, high-performance Flutter plugin that enables mobile applications to change their launcher app icon dynamically at runtime on Android and iOS without restarting the application or causing crashes.

Ideal for VIP / Premium subscriptions, dark mode matching, holiday / seasonal events, gamification tiers, and brand customization (like Telegram, Duolingo, and Revolut).

---

🌟 Key Features

• 🚀 Seamless Runtime Switching: Change app icons instantly while the app is running.
• 🤖 Android 14/15 Support: Smoothly switches activity aliases with DONT_KILL_APP flag to avoid abrupt restarts.
• 🍎 iOS 10.3+ to iOS 18+ Support: Full support for CFBundleAlternateIcons with optional alert suppression.
• 🔍 Auto-Discovery: Automatically detects all registered icon names from your configuration.
• ⚡ 100% Sound Null-Safe: Zero third-party bloat, pure native Kotlin and Swift bridge.

---

📦 Installation

Add dynamic_icon_plus to your pubspec.yaml:

dependencies:
  dynamic_icon_plus: ^0.1.0

Or install it via terminal:

flutter pub add dynamic_icon_plus

---

⚡ Automatic Icon Generator (Zero Manual Work! 🚀)

No need to manually resize icons or edit AndroidManifest.xml / Info.plist by hand!

1. Place your PNG icons inside assets/icons/:

my_flutter_app/
└── assets/
    └── icons/
        ├── dark_icon.png
        ├── gold_icon.png
        └── neon_icon.png

2. Run the built-in generator command:

dart run dynamic_icon_plus:generate

This single command automatically:

• 🤖 Generates all Android mipmap assets (mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi) into android/app/src/main/res/
• 🍎 Generates all iOS icon assets (@2x, @3x, 1024) into ios/Runner/
• 📝 Auto-configures AndroidManifest.xml by adding required <activity-alias> tags
• 📝 Auto-configures Info.plist by adding CFBundleAlternateIcons

---

🚀 Quick Start

import 'package:dynamic_icon_plus/dynamic_icon_plus.dart';

// 1. Check if dynamic icons are supported
bool supported = await DynamicIconPlus.supportsAlternateIcons;

// 2. Get list of all available icons
List<String> icons = await DynamicIconPlus.getAvailableIcons();
print('Available icons: $icons'); // ['dark_icon', 'gold_icon', 'neon_icon']

// 3. Switch to a new icon
await DynamicIconPlus.setIcon('gold_icon');

// 4. Get currently active icon name
String? current = await DynamicIconPlus.currentIcon;
print('Current icon: $current'); // "gold_icon"

// 5. Restore default app icon
await DynamicIconPlus.reset();

---

📱 Platform Setup

🤖 Android Setup

In your android/app/src/main/AndroidManifest.xml, declare an <activity-alias> for each alternate icon you want to offer:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application
        android:label="Your App"
        android:icon="@mipmap/ic_launcher">
        
        <!-- Default Main Activity -->
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:launchMode="singleTop"
            android:theme="@style/LaunchTheme">
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity>

        <!-- Alternate Icon 1: dark_icon -->
        <activity-alias
            android:name=".MainActivity.dark_icon"
            android:enabled="false"
            android:exported="true"
            android:icon="@mipmap/ic_launcher_dark"
            android:targetActivity=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity-alias>

        <!-- Alternate Icon 2: gold_icon -->
        <activity-alias
            android:name=".MainActivity.gold_icon"
            android:enabled="false"
            android:exported="true"
            android:icon="@mipmap/ic_launcher_gold"
            android:targetActivity=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity-alias>

    </application>
</manifest>

---

🍎 iOS Setup

In your ios/Runner/Info.plist, add your alternate icons under CFBundleIcons:

<key>CFBundleIcons</key>
<dict>
    <key>CFBundlePrimaryIcon</key>
    <dict>
        <key>CFBundleIconFiles</key>
        <array>
            <string>AppIcon</string>
        </array>
    </dict>
    <key>CFBundleAlternateIcons</key>
    <dict>
        <key>dark_icon</key>
        <dict>
            <key>CFBundleIconFiles</key>
            <array>
                <string>dark_icon</string>
            </array>
            <key>UIPrerenderedIcon</key>
            <false/>
        </dict>
        <key>gold_icon</key>
        <dict>
            <key>CFBundleIconFiles</key>
            <array>
                <string>gold_icon</string>
            </array>
            <key>UIPrerenderedIcon</key>
            <false/>
        </dict>
    </dict>
</dict>

Place the @2x and @3x PNG files inside ios/Runner/ (e.g. [e-mail], [e-mail]).

---

📚 Complete API Reference

Method	Return Type	Description
DynamicIconPlus.supportsAlternateIcons	Future<bool>	Checks if the OS and device supports dynamic icons.
DynamicIconPlus.getAlternateIconName()	Future<String?>	Returns the active alternate icon name, or null if default.
DynamicIconPlus.getAvailableIcons()	Future<List<String>>	Returns all registered alternate icon names.
DynamicIconPlus.setAlternateIconName(name)	Future<void>	Switches the app icon to name (null resets to default).
DynamicIconPlus.resetToDefault()	Future<void>	Restores the default launcher icon.
DynamicIconPlus.setIcon(name)	Future<void>	Convenient shorthand for setAlternateIconName.
DynamicIconPlus.reset()	Future<void>	Convenient shorthand for resetToDefault.

---

📱 Interactive Demo Application

Run the bundled Flutter demo app in the example/ directory:

cd example
flutter run

---

🧪 Testing & Quality Assurance

flutter test

Output:

00:00 +8: All tests passed!

---

👨‍💻 Author & Contributions

Created with ❤️ by Ibrohim Qobilov.

Contributions, issues, and feature requests are welcome!

• GitHub Repository
• Report an Issue

---

📄 License

This package is open-sourced under the MIT License.