masterfabric_app_icon #

Build-time app icon generation and runtime icon changing with Flutter package.

✨ iOS 26 Liquid Glass Optimized - High-quality icon generation optimized for iOS 26's Liquid Glass design system with automatic retry logic for reliable icon switching.

📌 Note: This package was created for Ticimax applications. This is a reference package study.

Screenshots #

Current Icon Names #

Main Package (ios/) #

Example App (example/ios/) #

Installation #

dependencies:
  masterfabric_app_icon: ^2.0.0

Or add via command line:

flutter pub add masterfabric_app_icon

Quick Start #

1. Prepare Source Icons #

Place your 1024x1024 PNG (minimum 512x512, recommended 2048x2048 for iOS 26 Liquid Glass) files in the assets/app_icons/ folder:

iOS 26 Liquid Glass: For optimal quality with Liquid Glass effects (refraction, reflection, lensing), use 2048x2048 source images. The generator will automatically optimize them.

assets/app_icons/
├── appicons_trabzonspor.png
└── appicon_designer.png

2. Create Configuration File #

masterfabric_app_icon.yaml in the project root directory:

masterfabric_app_icon:
  source_path: assets/app_icons/
  
  android:
    output_path: android/app/src/main/res/
    launcher_name: ic_launcher_masterfabric
    generate_adaptive: true
  
  ios:
    output_path: ios/Runner/Assets.xcassets/
    icon_name_prefix: AppIcon-MasterfabricCore

  flavors:
    - name: dev
      source_icon: app_icon_dev.png
    - name: prod
      source_icon: app_icon_prod.png

3. Generate Icons #

dart run masterfabric_app_icon:generate

Runtime Icon Changing #

Flutter API #

Recommended API (iOS 26 compatible):

import 'package:masterfabric_app_icon/masterfabric_app_icon.dart';

// Check if dynamic icons are supported
final isSupported = await MasterfabricAppIcon.supportsAlternateIcons;

// Get current icon name (null if using default)
final currentIcon = await MasterfabricAppIcon.getAlternateIconName();

// List all available icons
final availableIcons = await MasterfabricAppIcon.getAvailableIcons();

// Change icon (with automatic retry for iOS 26)
await MasterfabricAppIcon.setAlternateIconName('dev');
await MasterfabricAppIcon.setAlternateIconName('prod');

// Revert to default icon
await MasterfabricAppIcon.setAlternateIconName(null);

// Change icon without alert (iOS only, use at your own risk)
await MasterfabricAppIcon.setAlternateIconName('dev', showAlert: false);

Legacy API (deprecated, but still supported):

// These methods are deprecated but work for backward compatibility
await MasterfabricAppIcon.changeIcon('dev');  // Use setAlternateIconName instead
final current = await MasterfabricAppIcon.getCurrentIcon();  // Use getAlternateIconName instead
final isSupported = await MasterfabricAppIcon.isSupported();  // Use supportsAlternateIcons instead

iOS 26 Compatibility #

Automatic Retry Logic: The plugin includes automatic retry logic for iOS 26 that handles transient errors:

• "Resource temporarily unavailable" errors
• "Input/output error" errors
• Error code 35 (EDEADLK) handling
• Up to 5 retries with exponential backoff

Liquid Glass Support:

• Optimized for iOS 26's Liquid Glass design system
• High-resolution icon generation (2048x2048 processing)
• Cubic interpolation for best quality
• App state validation (requires app to be active)

iOS Configuration #

⚠️ iOS 26 Critical: iOS 26 uses strict name resolution. Appiconset folder names must exactly match the CFBundleIconName value in Info.plist.

iOS 26 Required Format: Add to ios/Runner/Info.plist file using CFBundleIconName (not CFBundleIconFiles):

<key>CFBundleIcons</key>
<dict>
    <key>CFBundlePrimaryIcon</key>
    <dict>
        <key>CFBundleIconName</key>
        <string>AppIcon</string>
    </dict>
    <key>CFBundleAlternateIcons</key>
    <dict>
        <key>dev</key>
        <dict>
            <key>CFBundleIconName</key>
            <string>dev</string>
        </dict>
        <key>prod</key>
        <dict>
            <key>CFBundleIconName</key>
            <string>prod</string>
        </dict>
    </dict>
</dict>

iOS 26 Strict Name Resolution:

• The key in CFBundleAlternateIcons (e.g., dev) is the icon name used in code
• The value in CFBundleIconName (e.g., dev) must exactly match the appiconset folder name
• Appiconset folder: dev.appiconset (NOT AppIcon-MasterfabricCore-dev.appiconset)
• iOS 26 will show empty icon if names don't match exactly

Automatic Cleanup: Use --clean flag to automatically remove old appiconset folders with prefix-based naming before generating new iOS 26 compatible ones:

dart run masterfabric_app_icon:generate --clean

This removes:

• Old format: AppIcon-MasterfabricCore-{flavor}.appiconset
• Legacy: ios/Runner/App Icon/ folder (iOS 26 ignores root PNG icons)

iOS 26 Appiconset Requirements:

• Appiconset folder name: {flavor_name}.appiconset (e.g., trabzonspor.appiconset)
• Contents.json with all required sizes (automatically generated)
• All icon files present (including mandatory 1024x1024 for App Store)
• 1024x1024 icon is mandatory - missing it causes empty icon in iOS 26

Android Configuration #

After the <activity> tag in android/app/src/main/AndroidManifest.xml file:

<!-- Activity alias for dev icon -->
<activity-alias
    android:name=".dev"
    android:enabled="false"
    android:exported="true"
    android:icon="@mipmap/ic_launcher_masterfabric_dev"
    android:targetActivity=".MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.LAUNCHER"/>
    </intent-filter>
</activity-alias>

<!-- Activity alias for prod icon -->
<activity-alias
    android:name=".prod"
    android:enabled="false"
    android:exported="true"
    android:icon="@mipmap/ic_launcher_masterfabric_prod"
    android:targetActivity=".MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.LAUNCHER"/>
    </intent-filter>
</activity-alias>

Android Plugin Update: Update the getActivityAliases() method in android/src/main/kotlin/.../MasterfabricAppIconPlugin.kt:

private fun getActivityAliases(): List<String> {
    return listOf("dev", "prod")
}

Important Notes #

CLI Commands #

# Basic usage
dart run masterfabric_app_icon:generate

# With custom config
dart run masterfabric_app_icon:generate -c config.yaml

# Clean old iOS appiconsets and regenerate (iOS 26 recommended)
dart run masterfabric_app_icon:generate --clean

# Help
dart run masterfabric_app_icon:generate -h

iOS 26 Migration: If you're upgrading from an older version, use --clean flag to remove old appiconset folders with prefix-based naming (e.g., AppIcon-MasterfabricCore-trabzonspor.appiconset) and generate new iOS 26 compatible ones (e.g., trabzonspor.appiconset).

Generated Files #

Android #

android/app/src/main/res/
├── mipmap-mdpi/ic_launcher_masterfabric_dev.png (48x48)
├── mipmap-hdpi/... (72x72)
├── mipmap-xhdpi/... (96x96)
├── mipmap-xxhdpi/... (144x144)
├── mipmap-xxxhdpi/... (192x192)
└── mipmap-anydpi-v26/ic_launcher_masterfabric_dev.xml

iOS #

ios/Runner/Assets.xcassets/
├── AppIcon.appiconset/                    (Default icon - iOS 26 format)
│   ├── Contents.json
│   └── Icon-App-*.png (all sizes including 1024x1024)
├── dev.appiconset/                        (Alternate icon - iOS 26 format)
│   ├── Contents.json
│   └── Icon-App-*.png (all sizes including 1024x1024)
└── prod.appiconset/                       (Alternate icon - iOS 26 format)
    ├── Contents.json
    └── Icon-App-*.png (all sizes including 1024x1024)

iOS 26 Requirements:

• ✅ Appiconset folder name = flavor name (e.g., dev.appiconset, prod.appiconset)
• ✅ Must match CFBundleIconName in Info.plist exactly
• ✅ All icon sizes present (20x20, 29x29, 40x40, 60x60, 76x76, 83.5x83.5, 1024x1024)
• ✅ 1024x1024 is mandatory - missing it causes empty icon
• ✅ Contents.json in iOS 26 Icon Composer format

iOS 26 Liquid Glass Optimizations:

• Source images processed at 2048x2048 resolution
• Generated icons at correct sizes for each device
• Cubic interpolation for best quality
• Level 9 PNG encoding (maximum quality)
• Optimized for Liquid Glass effects (refraction, reflection, lensing)

Legacy Support (Deprecated):

• ios/Runner/App Icon/ folder is still generated for backward compatibility
• iOS 26 ignores these root PNG icons - only uses appiconset

iOS 26 Liquid Glass Features #

⚠️ Important: Alternate Icons & Liquid Glass #

iOS 26 Compatibility: Alternate app icons (CFBundleAlternateIcons) fully support Liquid Glass effects. The system automatically applies Liquid Glass to all app icons, including alternate icons.

What Works:

• ✅ Alternate icons receive Liquid Glass effects automatically
• ✅ Standard setAlternateIconName API fully supports Liquid Glass
• ✅ High-resolution icons (1024x1024) render beautifully with Liquid Glass
• ✅ All Liquid Glass effects (refraction, reflection, lensing) work with alternate icons

Potential Considerations:

• ⚠️ Some users may experience visual effects (icons may appear slightly tilted due to Liquid Glass refraction)
• ⚠️ Users can disable Liquid Glass effects via Settings > Accessibility > Display & Text Size > Reduce Transparency
• ⚠️ Private API (showAlert: false) may have limited Liquid Glass support - use standard API for best results

Best Practices:

• Use high-resolution source images (2048x2048 recommended)
• Ensure icons have good contrast for Liquid Glass effects
• Test icons on iOS 26 devices to verify appearance
• Use standard API (showAlert: true) for full Liquid Glass support

Automatic Optimization #

• High-Resolution Processing: Source images are processed at 2048x2048 for optimal Liquid Glass rendering
• Quality Enhancement: Cubic interpolation ensures sharp, high-quality icons
• PNG Optimization: Level 9 encoding for maximum quality without loss

Error Handling #

• Automatic Retry: Handles transient errors with up to 5 retries
• Exponential Backoff: Smart retry delays (0.5s, 1.0s, 1.5s, 2.0s, 2.5s)
• Error Codes: Supports error codes 5 (EIO), 16 (EAGAIN), 35 (EDEADLK)
• App State Validation: Ensures app is active before icon changes

Liquid Glass Effects #

The generated icons are optimized for iOS 26's Liquid Glass design system:

• Refraction: Content from below is refracted through the icon
• Reflection: Light from around the icon is reflected
• Lensing: Gorgeous lensing effect along icon edges

Troubleshooting #

iOS 26 Icon Change Errors #

If you encounter "Resource temporarily unavailable" or "Input/output error":

1. The plugin automatically retries (up to 5 times)
2. Ensure the app is in the foreground (active state)
3. Wait a moment and try again
4. Check that icons are properly configured in Info.plist

iOS 26 Icons Not Visible (Empty Icon) #

Root Cause: iOS 26 uses strict name resolution. If appiconset folder name doesn't exactly match CFBundleIconName, iOS shows empty icon (no error thrown).

Solution Checklist:

1. ✅ Use CFBundleIconName (Not CFBundleIconFiles):

   <key>CFBundleIconName</key>
   <string>dev</string>  <!-- Must match appiconset folder name exactly -->
   

2. ✅ Appiconset Folder Name Must Match:

   • Info.plist: CFBundleIconName = "dev"
   • Appiconset folder: dev.appiconset (NOT AppIcon-MasterfabricCore-dev.appiconset)
   • The generator now creates appiconset with flavor name directly

3. ✅ Verify All Icon Sizes Present:

   # Check appiconset folder
   ls -la ios/Runner/Assets.xcassets/dev.appiconset/
      
   # Must have 1024x1024 (mandatory for iOS 26)
   ls ios/Runner/Assets.xcassets/dev.appiconset/[email protected]
   

4. ✅ Regenerate Icons (New Format):

   dart run masterfabric_app_icon:generate
   # This will create: dev.appiconset, prod.appiconset (not AppIcon-MasterfabricCore-{flavor}.appiconset)
   

5. ✅ Clean and Rebuild:

   # In Xcode: Product → Clean Build Folder (Cmd+Shift+K)
   # Delete DerivedData: Window → Organizer → Projects → Delete DerivedData
   flutter clean
   flutter pub get
   flutter run
   

6. ✅ Remove Legacy App Icon Folder:

   # iOS 26 ignores root PNG icons - remove them
   rm -rf ios/Runner/App\ Icon/
   

iOS 26 Behavior:

• ❌ If appiconset name doesn't match → Empty icon (no error)
• ✅ If appiconset name matches exactly → Icon displays correctly
• ✅ All sizes must be present (especially 1024x1024)

Quick Fix for Existing Projects:

# 1. Clean old appiconsets and regenerate (RECOMMENDED)
dart run masterfabric_app_icon:generate --clean

# 2. Update Info.plist to use CFBundleIconName (see iOS Configuration section)

# 3. Xcode Build Settings - CRITICAL for iOS 26:
#    - Open ios/Runner.xcworkspace in Xcode
#    - Select Runner target
#    - Go to Build Settings tab
#    - Search for "Alternate App Icons" or "ASSETCATALOG_COMPILER_ALTERNATE_APPICON_NAMES"
#    - Add: dev prod (space-separated)

# 4. Verify appiconsets in Xcode:
#    - Navigate to Runner → Assets.xcassets
#    - Verify all appiconset folders are visible
#    - Right-click each appiconset → "Get Info" → Check "Target Membership" → Ensure "Runner" is checked

# 5. Clean Xcode build
# In Xcode: Product → Clean Build Folder (Shift+Cmd+K)
# Also: Window → Organizer → Projects → Delete DerivedData

# 6. Fresh Install (NOT update - iOS 26 requires fresh install):
#    - Delete app from device
#    - Rebuild and install: flutter run

# 7. Rebuild
flutter clean
cd ios && pod deintegrate && pod install && cd ..
flutter pub get
flutter run

Important iOS 26 Note: If alternate icons still don't appear after following the steps above:

1. Verify in Xcode: Open ios/Runner.xcworkspace and check that all appiconset folders are visible in Assets.xcassets
2. Check Target Membership: Each appiconset must have "Runner" target checked
   • Right-click each appiconset → "Get Info" → "Target Membership" → Ensure "Runner" is checked
3. Verify Appiconset Structure: In Xcode, open each appiconset and verify:
   • All icon sizes are present (especially 1024x1024)
   • Contents.json is valid
   • No missing or corrupted icon files
4. Check Xcode Console: When changing icons, check Xcode console for debug messages:
   • [MasterfabricAppIcon] Setting alternate icon: {name}
   • [MasterfabricAppIcon] ✅ Icon '{name}' found in CFBundleAlternateIcons
   • If you see warnings, the icon name doesn't match Info.plist
5. Restart Device: Sometimes iOS 26 requires a device restart to recognize new appiconsets
6. Verify Icon Names: Ensure the icon name used in code (e.g., 'dev') exactly matches:
   • The key in CFBundleAlternateIcons (Info.plist) - MUST BE EXACT
   • The CFBundleIconName value (Info.plist) - MUST BE EXACT
   • The appiconset folder name (e.g., dev.appiconset) - MUST BE EXACT
   • Case-sensitive! 'Dev' ≠ 'dev'

iOS 26 Critical Issue - Appiconset Not in Bundle: If appiconsets are visible in Xcode but icons don't appear in the app:

1. Xcode Build Settings - Alternate App Icons (CRITICAL for iOS 26):

   • Open ios/Runner.xcworkspace in Xcode
   • Select Runner target in the project navigator
   • Go to Build Settings tab
   • Search for "Alternate App Icons" or "ASSETCATALOG_COMPILER_ALTERNATE_APPICON_NAMES"
   • Add only alternate icon names (NOT default flavor) separated by spaces: dev prod
   • Important: Default flavor is the primary icon, NOT an alternate icon
   • This tells Xcode which appiconsets to include in the bundle
   • Reference: Apple Documentation

2. Target Membership:

   • In Xcode, select each appiconset folder → File Inspector → Target Membership → Ensure "Runner" is checked

3. Clean Build and Fresh Install:

   • Clean Build: Product → Clean Build Folder (Shift + Cmd + K)
   • Delete DerivedData: Window → Organizer → Projects → Delete DerivedData
   • Fresh Install: Delete the app from device → Reinstall (NOT update, must be fresh install)
   • iOS 26 requires fresh install to recognize alternate icons

4. Verify in Xcode:

   • Build Settings → Search "Alternate App Icons"
   • Should show: dev prod

iOS 26 Liquid Glass Visual Issues #

If icons appear distorted or tilted with Liquid Glass:

1. This is normal: Liquid Glass refraction can cause optical illusions
2. User Control: Users can disable via Settings > Accessibility > Reduce Transparency
3. Icon Design: Use high-contrast icons for best Liquid Glass appearance
4. Testing: Always test alternate icons on iOS 26 devices
5. Standard API: Use showAlert: true for full Liquid Glass support

Icon Quality Issues #

For best results with iOS 26 Liquid Glass:

• Use 2048x2044 source images when possible
• Ensure source images are square (1:1 ratio)
• Use PNG format with no transparency (alpha channel will be removed automatically)

License #

MIT