Splash screen nativa in Flutter con flutter_native_splash

Partiamo da un progetto nuovo (oppure usa il tuo progetto esistente):

flutter create splash_demo
cd splash_demo

Il pacchetto flutter_native_splash serve solo in fase di sviluppo, perché genera file nativi: va quindi aggiunto fra le dev_dependencies.

Puoi farlo da terminale oppure modificando a mano il pubspec.yaml. Dopo l'aggiunta, esegui flutter pub get per scaricare il pacchetto.

# da terminale
flutter pub add dev:flutter_native_splash

# equivale a scrivere nel pubspec.yaml:
# dev_dependencies:
#   flutter_test:
#     sdk: flutter
#   flutter_native_splash: ^2.4.0

flutter pub get

La splash nativa non è un widget Flutter: è un'immagine statica mostrata dal sistema operativo. Serve quindi un file PNG con sfondo trasparente.

Consigli pratici:

• usa un PNG quadrato di almeno 1152x1152 px (verrà ridimensionato automaticamente per tutte le densità);
• evita testo molto piccolo: su Android 12+ il logo viene ritagliato dentro un cerchio;
• tieni il contenuto grafico al centro, lasciando un margine di sicurezza del 30% circa attorno.

Crea la cartella assets/ nella radice del progetto e copiaci dentro il logo. Per questa splash non serve dichiarare l'asset nella sezione flutter: del pubspec: il pacchetto legge il file direttamente dal disco durante la generazione.

splash_demo/
├── assets/
│   ├── splash_logo.png        # logo per tema chiaro
│   └── splash_logo_dark.png   # logo per tema scuro (opzionale)
├── lib/
│   └── main.dart
└── pubspec.yaml

Aggiungi in fondo al pubspec.yaml (allo stesso livello di indentazione di flutter:, quindi a inizio riga) la sezione flutter_native_splash.

Le chiavi principali:

• color / color_dark: colore di sfondo per tema chiaro e scuro;
• image / image_dark: il logo mostrato al centro;
• android_12: sezione obbligatoria per Android 12 e versioni successive, che usa un formato diverso (icona circolare + colore di sfondo);
• android e ios: abilitano la generazione per le due piattaforme.

⚠️ Attenzione all'indentazione: lo YAML usa due spazi e non tollera i tab.

flutter_native_splash:
  color: "#ffffff"
  color_dark: "#121212"

  image: assets/splash_logo.png
  image_dark: assets/splash_logo_dark.png

  android: true
  ios: true
  web: false

  # Android 12+ richiede una configurazione dedicata
  android_12:
    image: assets/splash_logo.png
    image_dark: assets/splash_logo_dark.png
    color: "#ffffff"
    color_dark: "#121212"
    # dimensione consigliata dell'icona: 960x960 px entro un canvas 1152x1152
    icon_background_color: "#ffffff"
    icon_background_color_dark: "#121212"

Ora lanciamo il generatore: il pacchetto scriverà i file di risorse nativi (drawable, styles.xml su Android, LaunchScreen.storyboard e asset su iOS).

Dopo la generazione non basta un hot reload: le risorse native vengono lette solo all'avvio dell'app, quindi devi chiudere e rilanciare con flutter run (meglio ancora dopo un flutter clean se vedi la vecchia splash).

Ricorda: ogni volta che modifichi il colore o il logo nel pubspec devi rieseguire il comando di generazione.

# genera i file nativi
dart run flutter_native_splash:create

# se usi un file di configurazione separato
# dart run flutter_native_splash:create --path=splash.yaml

# riavvio pulito
flutter clean
flutter pub get
flutter run

Di default la splash sparisce appena Flutter disegna il primo frame. Se la tua app deve caricare preferenze, token o dati remoti, l'utente vedrebbe uno sfarfallio o una schermata vuota.

Il pacchetto mette a disposizione due metodi:

• FlutterNativeSplash.preserve(widgetsBinding: ...) — blocca la rimozione automatica;
• FlutterNativeSplash.remove() — la toglie quando sei pronto.

Importante: tra preserve e remove non deve passare troppo tempo (massimo 2-3 secondi), altrimenti l'utente percepisce l'app come lenta. Aggiungi sempre un try/catch per evitare di restare bloccato sulla splash in caso di errore.

import 'package:flutter/material.dart';
import 'package:flutter_native_splash/flutter_native_splash.dart';

Future<void> main() async {
  final binding = WidgetsFlutterBinding.ensureInitialized();
  // La splash resta visibile finché non chiamiamo remove()
  FlutterNativeSplash.preserve(widgetsBinding: binding);

  try {
    await _inizializzaApp();
  } catch (_) {
    // anche in caso di errore dobbiamo proseguire
  } finally {
    FlutterNativeSplash.remove();
  }

  runApp(const MyApp());
}

Future<void> _inizializzaApp() async {
  // simula il caricamento di preferenze, sessione, configurazioni...
  await Future<void>.delayed(const Duration(seconds: 2));
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Splash Demo',
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      darkTheme: ThemeData.dark(useMaterial3: true),
      home: const HomePage(),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Home')),
      body: const Center(child: Text('App pronta!')),
    );
  }
}

Ultimo passo: la verifica.

1. Cambia il tema del dispositivo (Impostazioni → Display → Tema scuro) e riavvia l'app: devi vedere color_dark e image_dark.
2. Su Android 12+ controlla che il logo non venga tagliato: se succede, riduci il contenuto grafico lasciando più margine trasparente.
3. Su iOS, se la vecchia splash resta in cache, disinstalla l'app dal simulatore e reinstallala.

Se vuoi tornare indietro, il pacchetto offre un comando che ripristina i file nativi originali: utile prima di cambiare completamente design o se la splash dà problemi di build.

Buone pratiche finali

• Non usare la splash nativa per mostrare pubblicità o messaggi: deve essere istantanea.
• Mantieni la splash coerente con la prima schermata dell'app (stesso sfondo) per un effetto di continuità.
• Versiona il pubspec.yaml: i file nativi generati si possono sempre ricreare con un comando.

# ripristina i file nativi di default
dart run flutter_native_splash:remove

# build di verifica
flutter build apk --debug
flutter build ios --debug --no-codesign