/flutter-pre-caching

name: flutter-pre-caching
description: "Use when preloading fonts, asset/network images, Lottie/Rive animations, local JSON/config, warming initial API data, or optimizing Flutter Web startup."
license: MIT

Pre-caching in Flutter and Flutter Web

Pre-caching helps avoid jank, loading flashes, font swaps, and delayed first renders.

The key rule:

> Pre-cache only what the user will likely see in the next 1 to 2 screens.

Do not pre-cache the whole app. That can slow startup and waste memory.

---

1. Google Fonts

Runtime Google Fonts preloading

Use `GoogleFonts.pendingFonts()` to load the font variants before showing text.

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

class ExampleSimple extends StatefulWidget {
  const ExampleSimple({super.key});

  @override
  State<ExampleSimple> createState() => _ExampleSimpleState();
}

class _ExampleSimpleState extends State<ExampleSimple> {
  late final Future<List<void>> googleFontsPending;

  @override
  void initState() {
    super.initState();

    googleFontsPending = GoogleFonts.pendingFonts([
      GoogleFonts.poppins(),
      GoogleFonts.montserrat(fontStyle: FontStyle.italic),
    ]);
  }

  @override
  Widget build(BuildContext context) {
    final pushButtonTextStyle = GoogleFonts.poppins(
      textStyle: Theme.of(context).textTheme.headlineMedium,
    );

    final counterTextStyle = GoogleFonts.montserrat(
      fontStyle: FontStyle.italic,
      textStyle: Theme.of(context).textTheme.displayLarge,
    );

    return FutureBuilder<List<void>>(
      future: googleFontsPending,
      builder: (context, snapshot) {
        if (snapshot.connectionState != ConnectionState.done) {
          return const SizedBox();
        }

        return Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(
              'You have pushed the button this many times:',
              style: pushButtonTextStyle,
            ),
            Text(
              '0',
              style: counterTextStyle,
            ),
          ],
        );
      },
    );
  }
}

Production recommendation

For production and offline support, prefer bundling critical fonts as assets.

flutter:
  fonts:
    - family: AppFont
      fonts:
        - asset: assets/fonts/AppFont-Regular.ttf
        - asset: assets/fonts/AppFont-Bold.ttf
          weight: 700

Use it in the app theme:

MaterialApp(
  theme: ThemeData(
    fontFamily: 'AppFont',
  ),
)

---

2. Asset images

Use `precacheImage` for images that appear soon.

@override
void didChangeDependencies() {
  super.didChangeDependencies();

  precacheImage(
    const AssetImage('assets/images/header.png'),
    context,
  );
}

Then use the image normally:

Image.asset('assets/images/header.png')

---

3. Network images

Use `precacheImage` with `NetworkImage`.

@override
void didChangeDependencies() {
  super.didChangeDependencies();

  precacheImage(
    const NetworkImage('https://example.com/image.png'),
    context,
  );
}

Then use it normally:

Image.network('https://example.com/image.png')

**Important:** `precacheImage` warms Flutter’s in-memory image cache. It does not provide long-term offline caching.

For disk caching, use a package like `cached_network_image`:

dependencies:
  cached_network_image: ^latest

Example:

CachedNetworkImage(
  imageUrl: 'https://example.com/image.png',
)

---

4. Multiple image preloading

@override
void didChangeDependencies() {
  super.didChangeDependencies();

  final images = <ImageProvider>[
    const AssetImage('assets/images/header.png'),
    const AssetImage('assets/images/avatar.png'),
    const NetworkImage('https://example.com/banner.png'),
  ];

  for (final image in images) {
    precacheImage(image, context);
  }
}

---

5. Waiting until images are ready

`precacheImage` returns a `Future<void>`, so you can wait before rendering the real UI.

late Future<void> _preloadImagesFuture;

@override
void didChangeDependencies() {
  super.didChangeDependencies();

  _preloadImagesFuture = Future.wait([
    precacheImage(
      const AssetImage('assets/images/header.png'),
      context,
    ),
    precacheImage(
      const NetworkImage('https://example.com/banner.png'),
      context,
    ),
  ]);
}

@override
Widget build(BuildContext context) {
  return FutureBuilder<void>(
    future: _preloadImagesFuture,
    builder: (context, snapshot) {
      if (snapshot.connectionState != ConnectionState.done) {
        return const CircularProgressIndicator();
      }

      return Column(
        children: [
          Image.asset('assets/images/header.png'),
          Image.network('https://example.com/banner.png'),
        ],
      );
    },
  );
}

> [!NOTE] > Use `didChangeDependencies`, not `initState`, when you need `context` for `precacheImage`.

---

6. What should normally be pre-cached on app start?

**Good candidates:**

• App logo
• First screen hero image
• First visible background image
• Current user avatar
• First visible card/list images
• Main font variants
• Small local config files
• Translations needed for first paint
• First API request
• Lottie/Rive animation shown immediately

**Bad candidates:**

• All product images
• All gallery images
• All remote feed images
• All icons in the app
• All route images
• Every image from every screen
• Large animations not shown immediately

---

7. Practical app-start preloader

class AppPreloader {
  const AppPreloader();

  Future<void> preload(BuildContext context) async {
    await Future.wait([
      _precacheImages(context),
      _loadCriticalAssets(),
      _warmUpInitialData(),
    ]);
  }

  Future<void> _precacheImages(BuildContext context) {
    return Future.wait([
      precacheImage(
        const AssetImage('assets/images/home_hero.png'),