masterfabric_app_icon

Pub Version Flutter License: MIT iOS 26

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

Splash Screen Icon Switcher How It Works Change Confirmation Success

Screenshot Description
Splash Screen App launch screen with Masterfabric branding
Icon Switcher Main interface showing current icon and available alternatives
How It Works iOS 26 icon change guide with step-by-step instructions
Change Confirmation System alert confirming the icon change
Success Confirmation screen after successful icon update

Current Icon Names

Main Package (ios/)

Icon Name Appiconset Folder Description
dev dev.appiconset Development environment icon
prod prod.appiconset Production environment icon

Example App (example/ios/)

Icon Name Appiconset Folder Description
AppIcon AppIcon.appiconset Default primary icon
icon1 icon1.appiconset Alternate icon 1 (Primary)
icon2 icon2.appiconset Alternate icon 2
icon3 icon3.appiconset Alternate icon 3 (Minimal)
designer designer.appiconset Designer theme icon
trabzonspor trabzonspor.appiconset Trabzonspor theme icon
ticimax ticimax.appiconset Ticimax theme icon

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

Topic Description
Source Size Minimum 512x512, ideal 1024x1024, recommended 2048x2048 for iOS 26 Liquid Glass
Format PNG, square format (1:1 ratio)
iOS 26 Optimization Automatic upscaling to 2048x2048, cubic interpolation, level 9 PNG encoding
iOS 26 Strict Naming Appiconset folder name must exactly match CFBundleIconName in Info.plist
iOS 26 CFBundleIconName Use CFBundleIconName (not CFBundleIconFiles) for iOS 26 compatibility
iOS 26 Build Settings CRITICAL: Add icon names to "Alternate App Icons" in Xcode Build Settings
iOS 26 1024x1024 1024x1024 icon is mandatory - missing it causes empty icon
iOS 26 Fresh Install Fresh install required (not update) for alternate icons to appear
Android Adaptive Background white, foreground centered at 66%
iOS Alternate Must be defined in Info.plist with CFBundleIconName
Android Alias Must be defined in AndroidManifest.xml
Launcher Refresh Icon change on Android may require launcher refresh
iOS 26 Retry Automatic retry logic handles transient errors (up to 5 retries)
App State iOS 26 requires app to be active (foreground) for icon changes
Private API Not supported in iOS 26 - always uses standard API

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

Libraries

masterfabric_app_icon
masterfabric_app_icon