simple_splash_view 0.3.2

Native splash generator (Android/iOS) with Kotlin/Swift using config from pubspec.yaml.

simple_splash_view

Native splash screen generator for Flutter apps. Configure the splash once in pubspec.yaml, then generate Android and iOS native code, resources, themes, and documentation from one command.

Arabic full guide: see ARABIC_GUIDE.md.

Features

• Android and iOS native splash screens generated from one config block.
• Lottie animation, static image, startup sound, text, background colors, and dark-mode variants.
• Loader styles: circular, linear, dots, pulse, wave, bounce, orbit, and custom Lottie loaders.
• Independent placement for loader and text with indicator_position and text_position.
• Platform targeting from the CLI: generate Android only, iOS only, or both.
• --init, --doctor, --preview, and --restore commands for a safer workflow.
• Cleanup command to remove generated splash files and native integrations.
• Automatic config validation and safety backups before native files are changed.
• Idempotent output: rerunning updates the same generated files instead of duplicating them.

Installation

dependencies:
  simple_splash_view: ^0.3.2

Declare every Flutter asset you use:

flutter:
  assets:
    - assets/splash/splash_light.json
    - assets/splash/splash_dark.json
    - assets/images/logo_light.png
    - assets/images/logo_dark.png
    - assets/loaders/loader.json
    - assets/audio/intro.mp3

Configuration

simple_splash_view:
  lottie: assets/splash/splash_light.json
  lottie_dark: assets/splash/splash_dark.json
  image: assets/images/logo_light.png
  image_dark: assets/images/logo_dark.png
  sound: assets/audio/intro.mp3
  text: "Loading..."
  ios_bundle_identifier: com.yourcompany.yourapp
  background_color: "#F4F5F7"
  background_color_dark: "#050505"
  text_color: "#1E1E1E"
  text_color_dark: "#FAFAFA"
  indicator: true
  indicator_style: dots
  indicator_color: "#FF5722"
  indicator_color_dark: "#FFC107"
  indicator_position: below_visual
  text_position: bottom
  indicator_offset_y: 0
  text_offset_y: 0
  visual_offset_y: -12
  visual_width: 200
  visual_height: 200
  indicator_width: 72
  indicator_height: 72
  text_size: 16
  duration: 4200
  theme:
    mode: system
    app_theme: "Theme.App"
    splash_theme: "Theme.Splash"

Real-device startup note: duration is used exactly as configured. For slower devices, values below 4200ms can finish before Flutter renders its first frame and may look blank or frozen. Use shorter values only when you have tested the target devices.

Loader Gallery

Pick a native loader or bring your own Lottie animation. Every style supports light/dark colors through indicator_color and indicator_color_dark.

circular	linear
[Circular loader preview]	[Linear loader preview]

dots	pulse
[Dots loader preview]	[Pulse loader preview]

wave	bounce
[Wave loader preview]	[Bounce loader preview]

orbit	lottie
[Orbit loader preview]	[Lottie loader preview]

Style	Preview	Best For	Config
circular	◌	Default native loading state	indicator_style: circular
linear	━━━━━━	Product launches and progress-like screens	indicator_style: linear
dots	● ● ●	Friendly animated loading	indicator_style: dots
pulse	⬤	Minimal branded splash screens	indicator_style: pulse
wave	▁ ▃ ▆	Premium launch screens with vertical motion	indicator_style: wave
bounce	● ˙ ●	Playful product and onboarding splash screens	indicator_style: bounce
orbit	◌ orbit	Futuristic brand splash screens	indicator_style: orbit
lottie	✦ custom motion ✦	Fully custom loaders from designers	indicator_style: lottie

Custom Lottie loader example:

simple_splash_view:
  indicator: true
  indicator_style: lottie
  indicator_lottie: assets/loaders/loader_light.json
  indicator_lottie_dark: assets/loaders/loader_dark.json

Placement

[Placement controls preview]

Key	Values	Behavior
indicator_position	auto, below_visual, above_text, top, center, bottom	Controls where the loader appears. Relative values follow the visual/text; absolute values pin to the screen.
text_position	auto, below_visual, top, center, bottom	Controls where the splash text appears.
indicator_offset_y	Any integer	Moves the loader vertically after placement. Positive moves down, negative moves up.
text_offset_y	Any integer	Moves the text vertically after placement. Positive moves down, negative moves up.
visual_offset_y	Any integer	Moves the main image/Lottie vertically while keeping it centered by default.
visual_width / visual_height	Positive integers	Main image/Lottie size. Defaults to 200x200.
indicator_width / indicator_height	Positive integers	Loader size override. Defaults depend on loader style. Built-in loaders scale internal parts to avoid overlap at small sizes.
text_size	Positive integer	Splash text size. Defaults to 16.

Set indicator: false to remove the loader from the next generated Android/iOS splash files. Set text to null or remove it to hide the splash text.

theme.mode supports system, light, and dark. On iOS and Android, system follows the device appearance, while light or dark forces the matching colors and asset variants.

Placement Recipes

Goal	Config
Brand in center, loader under logo, text at bottom	indicator_position: below_visual, text_position: bottom
Minimal loader only in the middle	indicator_position: center, text: null
Text and loader near the bottom	text_position: bottom, indicator_position: above_text
Push visual slightly higher	visual_offset_y: -40
Fine tune bottom text spacing	text_position: bottom, text_offset_y: -12

Theme Recipes

# Follow the device theme and use separate assets/colors.
theme:
  mode: system
background_color: "#FFFFFF"
background_color_dark: "#050505"
text_color: "#111827"
text_color_dark: "#FFFFFF"
indicator_color: "#FF5722"
indicator_color_dark: "#FFC107"

# Force a dark branded splash regardless of device appearance.
theme:
  mode: dark
background_color_dark: "#050505"
text_color_dark: "#FFFFFF"
indicator_color_dark: "#FFC107"

CLI

Create a starter config:

dart run simple_splash_view --init --preset brand

--init --preset brand appends a production-ready simple_splash_view block to pubspec.yaml, creates starter logo files under assets/images, and adds inline English comments beside the important keys so users understand what each option controls. The generated logo files are safe placeholders; replace them with your real brand assets when ready.

Generate both platforms:

dart run simple_splash_view

Generate one platform:

dart run simple_splash_view --platform android
dart run simple_splash_view --platform ios

Skip CocoaPods during iOS generation:

dart run simple_splash_view --platform ios --skip-pod-install

Diagnose the project:

dart run simple_splash_view --doctor

Generate a local HTML preview:

dart run simple_splash_view --preview

The preview opens automatically in your default browser and keeps a local preview server running. It renders configured images directly, renders main and loader Lottie JSON with lottie-web when available, and falls back to animated SVG when offline. It also includes Light/Dark/System theme buttons so you can verify both color sets. Press r then Enter in the terminal to regenerate and auto-reload the browser, or q then Enter to stop the preview server.

Remove generated splash integration:

dart run simple_splash_view --remove --platform all
dart run simple_splash_view --remove --platform android
dart run simple_splash_view --remove --platform ios

The remove command deletes generated splash files and removes launcher/AppDelegate integration. It intentionally preserves shared Gradle and CocoaPods dependencies because they may be used elsewhere in your app.

Restore the latest automatic backup:

dart run simple_splash_view --restore

Skip the automatic backup only when you already have source control coverage:

dart run simple_splash_view --no-backup

Presets

Preset	Use Case
minimal	Asset-free centered native loader with bottom text.
brand	Branded text, dots loader, bottom text, light/dark colors.
startup	Asset-free startup screen with linear loader.
bottom_loader	Loader and text grouped near the bottom.
center_loader	Loader-only splash centered on screen.

Configuration Reference

Key	Default	Description
image, image_dark	null	Static splash images.
lottie, lottie_dark	null	Main Lottie animation files.
sound	null	Optional startup audio.
text	null	Optional status text.
background_color, background_color_dark	#FFFFFF, #000000	Light and dark backgrounds.
text_color, text_color_dark	#111827, #FFFFFF	Light and dark text colors.
indicator	false	Enables or disables the loader.
indicator_style	circular	circular, linear, dots, pulse, wave, bounce, orbit, or lottie.
indicator_lottie, indicator_lottie_dark	null	Custom Lottie loader files.
indicator_position	auto	auto, below_visual, above_text, top, center, bottom.
text_position	auto	auto, below_visual, top, center, bottom.
indicator_offset_y	0	Moves loader vertically after placement.
text_offset_y	0	Moves text vertically after placement.
visual_offset_y	0	Moves main visual vertically after placement.
visual_width, visual_height	200, 200	Main image or Lottie size.
indicator_width, indicator_height	style default	Loader size override.
text_size	16	Text size in native sp/points.
duration	4200	Splash duration in milliseconds. Used exactly as configured; 4200+ is recommended for safer real-device startup.
theme.mode	system	system, light, or dark.
ios_bundle_identifier	auto repair	Optional explicit iOS bundle id.

What Gets Generated

Android

• SplashActivity.kt
• activity_splash.xml
• Generated color/style resources
• Generated drawable/raw assets, including dark-mode variants
• Manifest launcher integration
• Optional ProGuard keep rules

iOS

• SplashViewController.swift
• AppDelegate splash coordinator integration
• Embedded AppDelegate support for generated Swift coordinator/config code
• Resources copied under ios/Runner/Resources
• Generated resources registered in the Runner Copy Bundle Resources phase
• pod 'lottie-ios' when a main or loader Lottie file is configured
• Podfile validation and repair for Flutter-compatible CocoaPods hooks
• Automatic minimum iOS deployment target repair to 13.0
• Automatic flutter pub get before CocoaPods when generated Flutter config is missing

iOS Signing Note

If your app still uses a default com.example.* Bundle Identifier, the generator updates it automatically to a unique package-style identifier. For production apps, set ios_bundle_identifier explicitly in pubspec.yaml, then rerun dart run simple_splash_view.

If Apple signing still fails, open ios/Runner.xcworkspace, select Runner, and confirm that the Bundle Identifier is available for your development team.

License

MIT. See LICENSE.