DOCSEARCHbyAlgolia
Submit Docs

flutter_native_splash

repository·master·Indexed 23 days ago

https://github.com/jonbhanson/flutter_native_splash

A tool for automatically generating native iOS, Android, and Web code to customize the splash screen shown while a Flutter app is loading. It supports background colors, splash images, branding images, and specific requirements for Android 12+. The package includes a CLI for generation, support for multiple flavors via configuration files, and programmatic control of the splash screen lifecycle using preserve() and remove() methods.

Tokens
3.7K
Snippets
8
Records
21
Agent score
80%

What's inside flutter_native_splash

  1. Understand how the package modifies native files

    master

    The flutter_native_splash package automates the modification of platform-specific files. Note: If you have manually modified these files, the plugin may not work correctly.

    Android

    • Resizes splash images to mdpi, hdpi, xhdpi, xxhdpi, and xxxhdpi drawables.
    • Adds a <bitmap> item to launch_background.xml.
    • Adds background color to colors.xml and references it in launch_background.xml.
    • Adds full-screen mode toggle code to styles.xml.
    • Places dark mode variants in drawable-night, values-night, etc.

    iOS

    • Resizes splash images to @3x and @2x.
    • Inserts color and image properties into LaunchScreen.storyboard.
    • Implements background color by stretching a single-pixel PNG to fit the screen.
    • Adds hidden status bar toggle code to Info.plist.

    Web

    • Creates a web/splash folder for images and CSS.
    • Resizes splash images to 1x, 2x, 3x, and 4x in web/splash/img.
    • Adds the splash stylesheet and HTML elements to web/index.html.

  2. Configure splash screens for Android 12 and later

    master

    Android 12+ uses a different splash screen composition consisting of a window background, an icon, and an icon background. Note that background images are not supported on these versions.

    Key Considerations:

    • image parameter: By default, the launcher icon is used.
      • For icons without a background: Use 1152×1152 px (fits within a 768 px diameter circle).
      • For icons with a background: Use 960×960 px (fits within a 640 px diameter circle).
    • icon_background_color: Optional; used to increase contrast between the icon and the window background.
    • branding: The branding image dimensions must be 800x320 px.
    • Masking: One-third of the foreground is masked.
    • color: The window background must be a single opaque color.

    Known Limitations:

    • The splash screen may not appear when launching from Android Studio on API 31 (resolved in API 32+).
    • Non-Google launchers may not display the launch image correctly.
    • The splash screen does not appear when launching the app from a notification.

  3. Implement flavor support for multiple splash screens

    master

    To support multiple environments (e.g., production, development), you can create separate configuration files for each flavor using the pattern flutter_native_splash-<flavor>.yaml.

    1. Setup Configuration Files

    Create a file for each flavor in your project root. For example, flutter_native_splash-development.yaml:

    flutter_native_splash:
  color: "#ffffff"
  image: assets/logo-development.png
  branding: assets/branding-development.png
  color_dark: "#121212"
  image_dark: assets/logo-development.png
  branding_dark: assets/branding-development.png

  android_12:
    image: assets/logo-development.png
    icon_background_color: "#ffffff"
    image_dark: assets/logo-development.png
    icon_background_color_dark: "#121212"

  web: false

    2. Generate Splash Screens

    Use the CLI to generate screens for specific flavors or all of them at once.

    Generate a single flavor:

    dart run flutter_native_splash:create --flavor <flavor_name>

    Generate multiple specific flavors:

    dart run flutter_native_splash:create --flavors development,staging,production

    Generate all flavors automatically: This command scans for all flutter_native_splash-*.yaml files and generates them.

    dart run flutter_native_splash:create --all-flavors
# OR
dart run flutter_native_splash:create -A

    3. Platform Specific Setup

    Android

    No additional setup is required as long as your flavor names match your config file suffixes.

    iOS

    Since iOS requires manual linking of Storyboards for different schemes:

    1. Open Runner.xcworkspace in Xcode.
    2. Locate the new Storyboard files in {project root}/ios/Runner/Base.lproj.
    3. Drag and drop them into the Xcode project navigator (next to LaunchScreen.storyboard), selecting 'Copy if needed'.
    4. In the Runner target -> Build Settings -> All/Combined:
      • Add a User-Defined Setting named LAUNCH_SCREEN_STORYBOARD.
      • For each flavor/scheme, enter the exact name of the generated Storyboard (e.g., LaunchScreenDevelopment).
    5. In your Info.plist, find 'Launch screen interface file base name' and change its value to $(LAUNCH_SCREEN_STORYBOARD).
    dart run flutter_native_splash:create --all-flavors

  4. Install flutter_native_splash

    master

    Add flutter_native_splash to your pubspec.yaml dependencies. If you do not need to use the preserve() and remove() methods programmatically to control the splash screen lifecycle, you can place it in dev_dependencies instead.

    dependencies:
  flutter_native_splash: ^2.4.8

  5. Customize iOS launch screen assets manually

    master

    To customize the iOS launch screen with your own assets, you can use one of two methods:

    1. Direct File Replacement: Replace the existing image files directly within the ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory in your project.
    2. Xcode Interface:
      • Open your Flutter project's iOS workspace using open ios/Runner.xcworkspace.
      • In the Xcode Project Navigator, select Runner/Assets.xcassets.
      • Drag and drop your desired images into the asset catalog.
    open ios/Runner.xcworkspace

  6. Generate the native splash screen

    master

    To apply splash screen configurations defined in your pubspec.yaml (or a dedicated flutter_native_splash.yaml file), you must run the generation command in your terminal. This command generates the necessary iOS, Android, and Web native code to customize the background color and splash image.

    If your configuration is located in pubspec.yaml, run:

    flutter pub get
dart run flutter_native_splash:create

    If you are using a custom configuration file at a specific path, use the --path flag:

    flutter pub get
dart run flutter_native_splash:create --path=red.yaml
    dart run flutter_native_splash:create

  7. Configure the splash screen

    master

    Customize your splash screen by adding a flutter_native_splash: section to your pubspec.yaml or a dedicated flutter_native_splash.yaml file in your project root.

    Important Rules:

    • Color vs Background Image: You must choose between specifying a color (required) OR a background_image (required). They cannot be used together.
    • Android 12+: Settings in the main configuration block do not affect Android 12 and later. You must use the android_12 section to configure splash screens for these versions.
    • Platform Disabling: You can disable the package for specific platforms using android: false, ios: false, or web: false.
    flutter_native_splash:
  color: "#42a5f5"
  image: assets/splash.png
  fullscreen: true

  android_12:
    color: "#42a5f5"
    image: assets/images/logo/blank.png
    icon_background_color: "#111111"

  8. Generate native splash screens using the CLI

    master

    Use the flutter_native_splash:create command to generate the native iOS, Android, and Web code required for your splash screen based on your configuration files (typically pubspec.yaml or flutter_native_splash.yaml).

    If your configuration is in the default location, run:

    dart run flutter_native_splash:create

    If your configuration is in a specific file or directory, use the --path option.

  9. Configure splash screens for multiple flavors

    master

    The CLI supports generating splash screens for different app flavors using specific configuration files named flutter_native_splash-<flavor_name>.yaml. You can target these in three ways:

    1. Single Flavor: Use --flavor <name> to target one specific flavor.
    2. Specific List: Use --flavors <flavor1>,<flavor2> to provide a comma-separated list.
    3. All Flavors: Use --all-flavors to automatically find and generate splash screens for every file matching the flutter_native_splash-*.yaml pattern in the current directory.

  10. Troubleshoot iOS splash screen issues

    master

    If the splash screen does not update correctly on iOS, or if you see a white screen before the splash screen appears, follow these steps:

    1. Run flutter clean and recompile your app.
    2. If the issue persists, delete the app from the device, power down the device, power it back up, and then reinstall and launch the app.

  11. Troubleshoot common splash screen issues

    master

    Error: 'module flutter_native_splash' not found

    Solution: Run pod install inside your app's ios folder.

    Warning: 'A splash screen was provided to Flutter, but this is deprecated.'

    Cause: This is caused by legacy code in your android/app/src/main/AndroidManifest.xml. Solution: Remove the following metadata block:

    <meta-data
 android:name="io.flutter.embedding.android.SplashScreenDrawable"
 android:resource="@drawable/launch_background"
 />

    Note: Removing this will also remove the fade effect between the native splash and the app.

    Error: AAPT: error: style attribute 'android:attr/windowSplashScreenBackground' not found

    Cause: Your project is not configured for Android 12+. Solution: Update your app's build configuration to support Android 12.

    Issue: White screen between splash screen and app

    1. iOS Caching: This may be an iOS splash caching bug. Try uninstalling the app, restarting the device, and reinstalling.
    2. Initialization Delay: If your app takes time to initialize, use the preserve and remove calls provided by the package to keep the splash screen visible during startup.

    Issue: Flash of the wrong splash screen on iOS

    Solution: This is an iOS caching bug. Uninstall the app, power off the device, power it back on, and reinstall.

  12. Control splash screen lifecycle with preserve() and remove()

    master

    By default, the splash screen disappears when Flutter draws its first frame. To keep the splash screen visible during app initialization (e.g., while loading data or services), use FlutterNativeSplash.preserve() and FlutterNativeSplash.remove().

    1. Call FlutterNativeSplash.preserve(widgetsBinding: widgetsBinding) in your main() function after ensuring bindings are initialized.
    2. Call FlutterNativeSplash.remove() once your initialization logic is complete.
    import 'package:flutter_native_splash/flutter_native_splash.dart';

void main() {
  WidgetsBinding widgetsBinding = WidgetsFlutterBinding.ensureInitialized();
  FlutterNativeSplash.preserve(widgetsBinding: widgetsBinding);
  runApp(const MyApp());
}

// whenever your initialization is completed, remove the splash screen:
    FlutterNativeSplash.remove();