flutter_native_splash configuration and native code generation

The Flutter startup gap addressed by flutter_native_splash

Flutter does not draw its first Dart frame until the native application has loaded the Flutter runtime. During that interval, the README says the native application normally shows a white splash screen. For an engineer, this creates a cross-platform configuration problem: Android, iOS, and Web do not use exactly the same native assets or presentation rules, while the visible result must remain consistent with the Flutter application that follows it.

flutter_native_splash addresses that startup interval by generating platform code rather than drawing the splash from a Dart widget. Its target users are Flutter developers who need a repeatable way to specify a background color, a central splash image, platform-specific variants, and dark mode assets. Generation is also useful in a repository because the intent can remain in `pubspec.yaml` or `flutter_native_splash.yaml` rather than being scattered across native resource and configuration files.

The package does not shorten Flutter startup or provide a Dart-side startup screen. Its scope is the native launch experience before Flutter content appears. That distinction matters when choosing the tool: it solves asset generation and native platform customization, not startup performance.

Configuration flow from pubspec.yaml to native resources

The configuration flow begins with a `flutter_native_splash` block in the Flutter project. The README also permits a separate file at the project root named `flutter_native_splash.yaml`. From that declaration, `dart run flutter_native_splash:create` generates the native code for the configured platforms.

General settings apply across supported platforms, with a separate key available for each platform. For example, `color_android`, `color_ios`, and `color_web` can override a general `color`. Equivalent platform-specific keys exist for dark colors, background images, central images, and branding. An Android platform value therefore takes precedence over the general value when it is active. This allows one project to share assets where that is sufficient while using different artwork where platform dimensions or presentation rules require it.

The general `image` asset is separate from `background_image`. The README marks either a required color or a required background image as the choice for the general configuration, and states that those two required choices cannot be used together. The foreground `image` is a distinct setting. This distinction may feel overly strict, but it prevents an ambiguous configuration between the splash background and the image displayed above it.

Platform controls are also explicit. Setting `android`, `ios`, or `web` to `false` disables generation for that platform. Android alignment is controlled through `android_gravity`, iOS image scaling through `ios_content_mode`, and Web behavior through `web_image_mode`. These are native presentation controls, not Dart layout properties.

Installing flutter_native_splash and generating the first splash

Add the documented package dependency to `pubspec.yaml`. The README specifies version constraint `^2.4.8`.

dependencies:
  flutter_native_splash: ^2.4.8

Resolve the dependency with the Flutter package manager command given by the project documentation.

flutter pub get

Next, add a `flutter_native_splash` section to `pubspec.yaml`, or place it in `flutter_native_splash.yaml` at the project root. This first configuration sets a general color and foreground image.

flutter_native_splash:
  color: "#42a5f5"
  image: assets/splash.png

The generator reads that declaration and writes the native splash configuration.

dart run flutter_native_splash:create

If the configuration is not stored in either recognized file in the project root, pass its path with `-p`.

dart run flutter_native_splash:create -p ../your-filepath.yaml

After generation, inspect the platform directories for the created Android, iOS, and Web resources. The README does not provide device commands or expected screenshots for an initial run, so it does not support a more specific verification procedure beyond checking the generated files and opening the application in the target environments.

Android 12 and later configuration outside the general settings

The largest documented constraint is the split between older Android releases and Android 12 and later. The README explicitly states that the general `color`, `background_image`, `image`, and related parameters do not configure Android 12 and later because those releases handle splash screens differently. It directs developers to the `android_12` section at the end of the configuration instead.

That boundary prevents a common false result. A visually correct color or image under the general Android settings does not prove that Android 12 and later received the intended configuration. A team adopting the package must inspect the native Android output and configure both paths when the application supports the affected operating-system versions.

Android placement and scaling also require native concepts. `android_gravity` accepts values documented by the package, including `center`, `bottom`, `left`, `right`, and combinations such as `fill|clip_vertical`. `android_screen_orientation` can set an Android screen orientation value, while `android_min_sdk` lets the generator account for the project's minimum SDK when merging or removing styles and drawables.

The README excerpt does not show the required keys inside `android_12`, so this article does not invent them. Projects must consult the complete package documentation for that section before generation.

Dark mode, Web images, and platform asset constraints

Dark mode is expressed through paired settings such as `color_dark`, `image_dark`, and `background_image_dark`, with Android, iOS, and Web variants available for each category. The package therefore treats dark mode as an asset and color selection problem rather than a runtime Dart theme decision. Platform-specific dark values override their general dark counterparts, just as their light-mode counterparts override general values.

Asset types differ by role. The general foreground image must be a PNG and should be sized for 4x pixel density. Branding should also be PNG according to the README. The documented Web image examples use GIF files, while the platform-specific image settings show a Web GIF path. Background images are configured separately from foreground images, so a project must keep its file paths aligned with the intended visual layer.

Branding can be placed at `bottom`, `bottomRight`, or `bottomLeft`. `branding_bottom_padding` applies generally, with Android and iOS variants, but the README states that bottom padding for Web branding is not yet available. Web image mode accepts `center`, `contain`, `stretch`, or `cover`. These options affect how the generated asset is presented, not how Flutter scales widgets after startup.

This configuration surface is broad, but it is declarative. The README does not document asset validation messages, fallback behavior, or generated file contents. Incorrect dimensions, paths, or unsupported asset formats may therefore need to be diagnosed by inspecting assets and generated platform files.

Regeneration, cleanup, and the manual native alternative

flutter_native_splash is most useful when splash configuration is repeated across local builds, CI tasks, or multiple contributors. The README gives a matching removal command for restoring Flutter's default white native splash screen. The same default configuration file names are used for creation and removal.

dart run flutter_native_splash:remove

For a configuration outside `pubspec.yaml` and `flutter_native_splash.yaml`, the removal command accepts the same path option.

dart run flutter_native_splash:remove -p ../your-filepath.yaml

If generated resources cause trouble, the README specifically suggests cleaning the Flutter project and restoring package resolution.

flutter clean ; flutter pub get

The real alternative is editing Android, iOS, and Web splash resources directly in each platform project. That approach avoids relying on a generator, but it creates separate sources of truth and requires engineers to understand platform-specific settings themselves. The package takes the opposite approach: declare assets and platform options in YAML, then generate native code. The trade-off is that Android 12 and later still require separate attention, and developers must inspect or edit the generated output when native requirements extend beyond the documented configuration.

MIT licensing and flutter_native_splash maintenance history

The repository declares the MIT License. That identifies the license recorded for the package, but it does not answer project-specific questions about asset ownership, trademark permission, or whether separate artwork can be distributed. Teams should review the repository's `LICENSE` file and the rights attached to each image. The package license should not be treated as permission for every file placed in `assets/`.

The repository is not archived, and its last push was on 2026-05-29. Published release history includes `v2.4.8` on 2026-06-01, `v2.4.7` on 2025-10-17, and `v2.4.6` on 2025-04-06. These records show recent package activity, but they do not establish that every platform configuration remains equally stable.

For an adopting project, the main maintenance cost is reviewing version constraints and regenerating native files after changing the package. The package dependency is written directly into `pubspec.yaml`, so normal Dart dependency upgrades apply. The README also shows cleanup as a troubleshooting step, indicating that regeneration can require normal Flutter project cleanup and dependency resolution. The release history does not document a formal compatibility policy for every Flutter SDK or mobile platform.

Editorial conclusion

Adopt flutter_native_splash when a Flutter team wants to generate and regenerate native splash resources from declared configuration instead of editing each platform separately. Do not adopt it as a single, universal setup because Android 12 and later require a separate configuration section. Verify the generated files in `android/`, `ios/`, and `web/`, then run `flutter clean` and `flutter pub get` before treating a difficult configuration issue as a package defect.

Frequently asked questions

Official sources

1. jonbhanson/flutter_native_splash on GitHub
2. License: MIT
3. Project website
4. README
5. Releases