DEV Community: Thanasis Traitsis

Building Local Notifications in Flutter...Properly

Thanasis Traitsis — Mon, 08 Jun 2026 21:34:37 +0000

Have you ever added local notifications to a Flutter app and felt like you were just... copying lines without really knowing what you were doing? flutter_local_notifications, a manifest entry, a permission request, a scheduled call. It works. Sometimes. On some devices. With some Android versions. And when it doesn't, you have no idea why.

I've been there too. Recently, while working on a side project of mine called My Eyes (an optical health tracker), I wanted to remind users to replace their contact lenses a few days before expiry. Sounded simple. Schedule a notification 27 days from now, done. But the more I dug into it, the more I realized I didn't actually understand any of it. What does the operating system do with that schedule? Why are there three different permissions on Android and they all look similar? What's the difference between a "notification" and a "channel"? Why does the package force me to use TZDateTime instead of a normal DateTime?

So I went down the rabbit hole. And the deeper I went, the more I realized that most notification tutorials out there don't really teach you how notifications work. They teach you how to copy-paste the API. That's not enough. Because the moment something goes wrong, and trust me, it will, you need the mental model to debug it. This article is the long-form version of everything I learned. We're going to cover the local notification system in Flutter, from the very first moment your app says "hey OS, I want to schedule this" to the moment the user taps the notification and lands inside your app. We will talk about the native side, the permissions, the channels, the payloads, the architecture, the tests. Everything.

One thing to set straight upfront. There are two kinds of notifications: local (scheduled by your app, fired by the device, no internet needed) and remote/push (sent from a server through FCM or APNs). Today we're only covering local. Push deserves its own deep dive, and I'll write that one as a part 2. So if you came here for backend-triggered notifications, the foundation we lay today will make that follow-up much easier. But the post itself is 100% local.

Here's everything we're going to cover in this article:

How Local Notifications Actually Work — the mental model every Flutter developer needs before writing a single line
The Three Packages and Why Each One Exists — why you need all three, not just one
Permissions: What Each One Actually Does — the two gates most tutorials only half-explain
Channels: Giving Users Control Over What They Hear — Android 8+ and what iOS does instead
Designing the NotificationService — this is where the code starts. If you're already comfortable with the concepts, jump straight here.
Wiring It Up: Inside init() — the startup sequence that has to run before anything else
Scheduling, Payloads, and Cancelling — the three methods that make the whole thing work
The Tap: Where the Stream Earns Its Keep — handling taps across all three app states

You know me by now... we're not just going to make it work. We're going to understand why it works the way it does. Let's begin.

Section 1: How Local Notifications Actually Work

Before we touch a single line of code, we need to clear up the biggest misconception most Flutter developers have about notifications. And it's not a small one. It's the kind that, once you understand it, you are truly aware of the code you write. Most developers think the notification system works like a timer running inside their app. You schedule something, your code waits, the time arrives, your code fires the notification. Simple, right?

That's not what happens at all.

When you "schedule a notification," your app doesn't keep track of anything. It doesn't wait. It doesn't hold a timer. What it actually does is hand a piece of paper to the operating system and walk away. That paper says: "Hey OS, please show this text, with this title, at this exact moment in time, with this sound, with this icon. Here's an ID in case I need to cancel it later. Thanks."

And then your app is done. The OS takes the paper, files it in its own internal scheduler, and your app has zero responsibility from that point on.

Wait...so the OS is doing all the work?

Yes. Exactly that. Both Android and iOS have a system-level service that runs continuously in the background, owned by the operating system itself, not by any individual app. On Android it's called AlarmManager. On iOS it's UNUserNotificationCenter. These services are running on your phone right now, holding scheduled notifications for dozens of apps you've installed.

When the scheduled moment arrives, the OS looks at its internal list, sees that something is due to fire, and displays the notification. Your app doesn't even need to be running. It can be killed. It can be in the background for hours. The phone can be on airplane mode. None of it matters. The OS is the one with the alarm clock, not your code.

So what does our app actually do?

Three things, and only three things:

Tell the OS what to schedule (the title, body, time, icon, sound, payload, etc.).
Tell the OS to cancel something previously scheduled, using the ID we gave it.
React to taps when the user opens a notification and lands inside our app.

The bridge between Dart and the OS

Now here's the obvious question: how does our Dart code talk to a native OS service?

Dart doesn't speak AlarmManager. It doesn't speak UNUserNotificationCenter. These are native APIs, written in Kotlin/Java on Android and Swift/Objective-C on iOS. So we need a translator. Something that takes our Dart instructions and turns them into the right native calls. That translator is exactly what the flutter_local_notifications package does. But more about packages are on the next section...

Section 2: The Three Packages and Why Each One Exists

So we agreed that our app is just a thin layer that hands instructions to the OS. Now the question is, what do we actually need on the Dart side to do that?

The honest answer is three packages. Not one. Not two. Three. And I know what you're thinking, "three packages just to show a notification? Really?" Yes, really. But by the end of this section, you'll understand why each one is non-negotiable. Each one solves a specific problem the other two can't.

Package 1: flutter_local_notifications

This is the one that does the actual work. We already talked about it in Section 1 — it's the bridge between your Dart code and the native OS notification service. When you call something like _plugin.zonedSchedule(...) in Dart, this package's native side picks it up and calls AlarmManager on Android or UNUserNotificationCenter on iOS.

So far so good. This is the package you'd reach for first, and it's the only one you'll directly interact with in your code. You'll call initialize, you'll call zonedSchedule, you'll call cancel. All of it goes through this package. It's the workhorse. But here's the thing. The moment you try to actually schedule a notification, you hit a wall. The package refuses to accept a plain Dart DateTime. It demands something called a TZDateTime. And that's where the second package comes in.

Package 2: timezone

Wait, why is this even a problem? Why isn't DateTime enough? Because DateTime lies to you about time. That sounds dramatic, but stick with me.

When you write DateTime(2027, 1, 28, 9, 0), what you're actually saying is "9:00 AM on January 28, 2027", in the timezone the device is currently in. But the device's timezone isn't a fixed thing. The user could travel. Daylight Saving Time could shift. The device could be in one zone when you schedule the notification, and in a completely different one when it's supposed to fire 27 days later.

So "9:00 AM" becomes ambiguous. Is it 9:00 AM in Athens, where the user was when they scheduled it? Or 9:00 AM in Tokyo, where they happen to be a week later? Without a timezone attached to the time, there's no correct answer.

This is exactly why flutter_local_notifications refuses to use plain DateTime. It would be a bug waiting to happen, especially around DST changes. So it forces you to use TZDateTime, which is a timezone-aware datetime. It carries its zone with it. "9:00 AM in Europe/Athens" is unambiguous, no matter where the device is when the alarm fires.

The timezone package provides this TZDateTime class, plus the entire IANA timezone database (every timezone on Earth, with every historical DST rule), compiled into the package. When you initialize it, your app loads that database into memory once, and from then on you can work with any timezone in the world with full precision.

So now we have: the package that talks to the OS (flutter_local_notifications), and the package that knows about every timezone in existence (timezone). But we're still missing something. What's the device's current timezone?

Package 3: flutter_timezone

The timezone package knows about Athens. It knows about Tokyo. It knows about every IANA zone ever defined. But it doesn't know which one your device is currently in.

To answer that question, we need to ask the OS directly. "Hey OS, what timezone are you currently set to?" And that's what flutter_timezone does. It's a tiny package that makes one platform-channel call to Android or iOS and returns a string like "Europe/Athens". That's all. That's the whole package. So, to summarize everything, let's look at the three packages side by side:

flutter_local_notifications → the bridge to the OS
timezone → the library of every timezone rule in the world
flutter_timezone → asks the device which timezone it's currently in

Each one solves a problem the others can't. The first one alone is useless because it can't accept naive times. The second one alone is useless because it doesn't know what "local" means. The third one alone is useless because it's just a string-fetcher with no scheduling capability.

Section 3: Permissions: What Each One Actually Does

This is the section most notification tutorials either skip entirely or get completely wrong. And the consequence is a specific, frustrating bug. Your code is correct. The package is initialized. The schedule call succeeds. And yet, the notification never appears. No error. No crash. Nothing.

Almost every time, the answer is permissions.

But here's where people get confused. When they hear "notification permissions," they think of one thing, the dialog that pops up and asks "Allow My App to send you notifications?" That dialog is real, and it matters. But it's only half the story. There are actually two completely separate permission gates standing between your code and a notification that fires at the right moment. And most tutorials only tell you about one of them.

POST_NOTIFICATIONS: the visibility gate

The first gate controls a simple question: can your app show notifications in the user's tray at all?

This is the permission that controls the visible banner, the sound, the lock screen entry, everything the user actually sees. Without it, your notifications are scheduled correctly, they even fire internally, but they are silently discarded before ever reaching the screen.

Now here's where Android's history makes things complicated. The rule has changed depending on which version of Android your user is running:

Android 12 and below → notification display was granted automatically at install. No prompt, no dialog. Your app could show notifications the moment it was installed.
Android 13 and above → POST_NOTIFICATIONS became a runtime permission. Your app must explicitly ask the user for it. The user sees a dialog. If they tap "Don't allow", the OS won't show the dialog again. The user has to go into Settings manually to re-enable it.

The same notification code behaves completely differently depending on the device. On an old device, it just works. On a modern device, it's blocked until the user explicitly grants it. If you skip this permission on Android 13+, your notifications will silently fail on the majority of active Android devices today.

One golden rule about when to request this permission: never ask at app launch. Ask at the exact moment the feature becomes relevant, when the user takes an action that would benefit from notifications. That moment of context is what turns a cold permission prompt into something the user actually understands and is likely to accept.

USE_EXACT_ALARM vs SCHEDULE_EXACT_ALARM: the timing gate

The second gate is completely separate from the first. It doesn't control whether a notification appears. It controls whether it appears at the precise moment you specified.

Without an exact-alarm permission, Android's battery optimizer is free to batch your alarm with other apps' alarms and fire them all together at a convenient moment. Your "fire at 9:00 AM" might fire at 9:47 AM. Or later. On Doze mode (Android's deep sleep state) the delay can be hours.

For a time-sensitive reminder, this is unacceptable. So Android introduced exact-alarm permissions to let apps opt into precise scheduling. But here's the thing: there are two versions of this permission, and the difference is not about capability. They do the exact same thing at runtime. The difference is about how the permission is granted, and whether the user can take it back.

SCHEDULE_EXACT_ALARM is the older one, introduced in Android 12. It's granted automatically at install on most devices, but the user can revoke it at any time from Settings → Apps → Your App → Alarms & Reminders. If they revoke it and your code tries to schedule an exact alarm, it throws a SecurityException. You need to check canScheduleExactAlarms() before every scheduling call.

USE_EXACT_ALARM is the newer one, introduced in Android 13. It's granted at install and cannot be revoked. The user has no toggle for it in Settings. But Google Play enforces a strict policy: this permission is only for apps whose core function is timed reminders, like alarm clocks, calendar apps, medication trackers etc. If you use it for something that doesn't qualify, your listing can be removed.

The cleanest approach is to declare both in your AndroidManifest.xml, using the maxSdkVersion attribute to scope each one to the right Android version:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

<uses-permission
    android:name="android.permission.SCHEDULE_EXACT_ALARM"
    android:maxSdkVersion="32" />

<uses-permission android:name="android.permission.USE_EXACT_ALARM" />

maxSdkVersion="32" tells Android: "Only consider this permission on API 32 and below." On Android 13+ (API 33+), the OS sees USE_EXACT_ALARM instead. On Android 12, it falls back to SCHEDULE_EXACT_ALARM. One manifest. Both versions covered.

RECEIVE_BOOT_COMPLETED: The forgotten one

There's a third permission worth knowing about, and it's the one most developers discover the hard way. It's called RECEIVE_BOOT_COMPLETED, and it solves a very specific quirk of Android.

When an Android device reboots, the OS forgets every alarm that was ever scheduled by every app. AlarmManager is completely wiped. This means a user who restarts their phone will silently stop receiving reminders, with no indication that anything went wrong. Everything looked fine. Then the phone rebooted. And now, nothing.

RECEIVE_BOOT_COMPLETED gives your app permission to receive a signal the moment the device finishes booting. flutter_local_notifications uses this automatically to reschedule everything it had previously queued. You don't write any special code, you just declare the permission, and the plugin handles the rest:

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

iOS doesn't have this problem. The OS persists scheduled local notifications across reboots automatically. Just another quiet asymmetry between the two platforms.

What about iOS?

Compared to Android, iOS is almost refreshingly simple. There is one permission for local notifications, and it controls everything, the banner, the sound, the badge count. No exact-alarm distinction, no boot signal, no version fragmentation.

You don't declare anything in Info.plist. You don't add any entitlements. You just ask for permission in code at the right moment, and the OS shows this prompt:

"[Your App] Would Like to Send You Notifications"

Allow or Don't Allow. That decision sticks. If they tap Don't Allow, the OS won't show the prompt again, same as Android 13+, same "ask at the right moment" rule applies.

Two gates. Both must be open.

This is the most important takeaway from this entire section:

POST_NOTIFICATIONS controls whether the notification appears at all.
The exact-alarm permission controls whether it appears at the right time.

These are not alternatives. You don't choose between them. You need both. If you only have POST_NOTIFICATIONS, your notifications will show, but potentially an hour late. If you only have the exact-alarm permission, your alarms fire precisely but are silently discarded before the user ever sees them.

Think of it like a locked door with two deadbolts. Both must be open. One is not enough.

Keep that in mind as we move into the next section. Because before we write a single line of Dart, there's one more native concept we need to understand, and it's the one that gives users control over the notifications they receive.

Section 4: Channels: Giving Users Control Over What They Hear

If you've ever gone into your phone's settings and turned off notifications for a specific category of an app (say, disabling the promotional ones but keeping the important alerts) you just used a notification channel. Even if you didn't know it.

Channels are an Android-only concept, introduced in Android 8.0. iOS has nothing equivalent, and we'll get to why in a moment. But on Android, every single notification your app shows must belong to a channel. Without a channel, your notification won't display at all on Android 8 and above.

Why do channels exist?

Before Android 8, notification settings were all-or-nothing. Either your app could send notifications, or it couldn't. There was no middle ground. If you wanted to mute the promotional emails from an app but still receive the security alerts, you had two options: put up with everything, or turn off all notifications and miss the things that actually mattered. Channels were Android's solution to that problem. They hand granular control back to the user. Instead of one on/off switch per app, the user gets one switch per category. Your app declares the categories

"Reminders"
"Promotions"
"Security Alerts",

and the user decides which ones they want to hear from.

So what exactly is a channel?

A channel is a named category that carries a set of display settings. When you create one, you define:

An ID: a unique string that identifies this channel internally. "reminders", "order_updates", "security". This is what you reference when scheduling a notification.
A name: the user-facing label. This is what appears in the app's notification settings screen.
A description: a short explanation of what this channel is for. Also visible to the user in Settings.
An importance level: this controls how prominently the notification is displayed.

The importance level deserves a closer look, because it's the thing that most directly shapes the user experience:

Importance.min → appears silently in the shade, no icon in the status bar
Importance.low → appears quietly, no sound, status bar icon shows
Importance.defaultImportance → sound plays, status bar icon shows, but no pop-up banner
Importance.high → sound plays, status bar icon shows, and a heads-up banner slides down at the top of the screen
Importance.max → same as high, reserved for urgent alerts like incoming calls

For a reminder app, Importance.high is the right choice. The user opted into these reminders, they should be hard to miss.

The rule nobody tells you about

Here's the part that catches everyone off guard. Once you create a channel and the user has seen it in their settings, you cannot change its properties. Not the importance. Not the sound. Not the vibration. Those settings now belong to the user.

If you create a channel with Importance.high and later decide it should be Importance.low, calling createNotificationChannel again with the same ID does absolutely nothing. The channel already exists, and the OS ignores your updated settings entirely. The only way to change it is to create a new channel with a different ID, which leaves the old one as a dead orphan in the user's settings until they clear it manually.

This is why you need to think about your channels before you ship. Pick your IDs carefully. Pick your importance carefully. Once your users have the app installed, those decisions are locked.

The good news: creating a channel that already exists is completely safe. It's a no-op. Calling createNotificationChannel every time your app starts is fine, and actually the recommended approach.

What about iOS?

iOS doesn't have channels because Apple took a completely different philosophy. Instead of letting apps declare categories, Apple gives users control through Focus modes, per-app notification summaries, and system-level notification management. When you create channels in your Flutter code, they are completely ignored on iOS. The plugin handles this transparently, the channel creation call simply does nothing on the iOS side. You write the code once, and the platform figures out what to do with it.

What iOS does enforce is a hard limit: you can have at most 64 pending local notifications scheduled at any given time. Schedule a 65th and the OS quietly drops the oldest one. For most apps this never becomes an issue. But it's worth knowing, if your app ever needs to schedule dozens of reminders per user, you'll need to be deliberate about which ones matter most. Maybe this is "your useless tip of the day"...anyway 😅.

Channels and your app

For our demo app, we need exactly one channel. Something like:

const AndroidNotificationChannel channel = AndroidNotificationChannel(
  'reminders',                           // id
  'Reminders',                           // name
  description: 'Scheduled reminders.',
  importance: Importance.high,
);

But here's an interesting architectural question. What happens when your app grows and you need three, four, five channels? Do they all live scattered across different files? Do you hardcode their IDs as strings in multiple places and hope nothing ever gets out of sync?

This is exactly the kind of problem that compounds quietly as a codebase grows. And it's what we'll address in the next section, when we design the NotificationService, a single class that owns your entire notification system, keeps your channels in one place, and makes sure the rest of your app never needs to know how any of it works.

That's where we're going next.

Section 5: Designing the NotificationService

Let's talk about a mistake that's very easy to make. You just learned about channels, permissions, and the OS scheduler. Now you want to write the scheduling code. And the natural instinct is: "I have a button. When it's pressed, I schedule a notification. So the scheduling code goes... near the button."

And just like that, your notification logic is buried inside a widget. Or inside a cubit that happens to need notifications. Or scattered across three different files because three different features all need reminders.

That's the first thing we're going to get right.

One class, one responsibility

The rule is simple. All notification logic like initialization, channel creation, permission requests, scheduling, cancelling, tap handling, lives in exactly one class. We'll call it NotificationService.

This class lives in your core/services/ folder. Not inside any specific feature. Not next to your screens or your cubits. In core/, because it's a horizontal capability, something any feature in your app can use without that feature having any ownership over it.

Think about what this means in practice. When you add a second feature that also needs reminders, it doesn't write its own scheduling code. It calls NotificationService. When you add a third feature, same thing. The notification system doesn't grow. The callers grow. There's only ever one place in your codebase that knows how to talk to the OS notification service. That makes it easy to test, easy to update, and impossible to get out of sync with itself.

NotificationService is registered as a singleton in your dependency injection setup. One instance, created once, alive for the entire lifetime of the app. The plugin it wraps maintains internal state that shouldn't be duplicated. Creating multiple instances would be a bug.

The most important design decision: primitives only

Here's the design decision that separates a good notification service from a great one. And it's the one most people get wrong.

"What if I just pass my whole data object into the service? It already has the title, the date, everything I need."

Don't. The NotificationService should not know anything about your app's domain.

It shouldn't know about users, orders, tasks, products, or whatever your app is about. If it did, it would become a service that can only ever serve that one feature. The moment a second feature needs notifications, you're stuck, either you bloat the service with another domain type, or you duplicate the scheduling code elsewhere. Neither is good.

The clean solution is to make the service speak in primitives only:

An id as an int
A fireAt as a plain DateTime
A title as a String
A body as a String
A payload as a String?

That's it. The service doesn't know what a "task" is or what an "order" is. It receives a time and some text, and it schedules them. The responsibility of translating "this order ships on January 28" into "schedule an id=42 notification for January 25 at 9:00 AM with this title and body" belongs to the feature, not the service.

The translator lives outside the service. The service just executes.

This is what makes NotificationService truly reusable across every feature you'll ever build. Today and in the future.

The channels enum

Remember the problem we ended Section 4 with? Channels scattered across files, IDs hardcoded as strings in multiple places, one typo away from a silent bug.

The solution is an enum. One enum, one file, one source of truth for every channel your app will ever declare:

enum AppNotificationChannel {
  reminders(
    id: 'reminders',
    name: 'Reminders',
    description: 'Scheduled reminders from the app.',
    importance: Importance.high,
  );

  const AppNotificationChannel({
    required this.id,
    required this.name,
    required this.description,
    required this.importance,
  });

  final String id;
  final String name;
  final String description;
  final Importance importance;
}

Now every channel in your app is a typed value. When you reference AppNotificationChannel.reminders, your IDE autocompletes it. If you rename it, every reference updates. If you delete it, the compiler tells you everywhere it was used. A typo in a channel ID is now a compile error, not a silent runtime failure.

Adding a new channel in the future is one new enum value. That's it.

Inside NotificationService, the scheduleReminder method accepts a channel directly from this enum. The service uses the channel's id, name, description, and importance without knowing anything else about where the notification is coming from:

Future<void> scheduleReminder({
  required int id,
  required DateTime fireAt,
  required String title,
  required String body,
  required AppNotificationChannel channel,
  String? payload,
});

The service doesn't decide which channel a notification belongs to. The caller does. The service just uses what it's given.

A quick preview: the stream

There's one more thing NotificationService owns that we haven't discussed yet: tap handling.

When the user taps a notification, something in your app needs to react (navigate to a screen, refresh some data, show a dialog). But taps can happen in any app state: while the app is open, while it's in the background, or when the app was completely closed and the tap is what launched it. Wiring all three of those scenarios into one place requires a mechanism that multiple parts of your app can subscribe to independently.

That mechanism is a Stream. The NotificationService exposes a Stream<String?> called onTap. Whenever a notification is tapped, the payload string is pushed into this stream. Any part of your app that cares subscribes to it and reacts.

We'll go deep on how streams work, and why this is the right choice here, in Section 8. For now, just know it exists, and it's one of the most important pieces of the whole system.

The skeleton

Here's what NotificationService looks like before we fill in any implementation. Read it slowly. Notice what's there and, just as importantly, what isn't:

@singleton
class NotificationService {
  NotificationService();

  final FlutterLocalNotificationsPlugin _plugin =
      FlutterLocalNotificationsPlugin();

  final StreamController<String?> _tapPayloads =
      StreamController<String?>.broadcast();

  Stream<String?> get onTap => _tapPayloads.stream;

  Future<void> init() async {
    // Timezone setup, plugin initialization,
    // channel registration, cold-start handling.
    // Coming in Section 6.
  }

  Future<bool> requestPermissions() async { ... }

  Future<void> scheduleReminder({
    required int id,
    required DateTime fireAt,
    required String title,
    required String body,
    required AppNotificationChannel channel,
    String? payload,
  }) async { ... }

  Future<void> cancel(int id) async { ... }

  void _onTap(NotificationResponse response) {
    _tapPayloads.add(response.payload);
  }
}

Notice what this class does not contain. No app-specific logic. No domain knowledge. No hardcoded strings. It receives instructions, executes them, and reports back. That's the whole job.

In the next section, we fill in every method. Starting with init(), the most important call in the whole system, and the one that has to happen before anything else.

Section 6: Wiring It Up: Inside init()

We have a skeleton. We understand why it's designed the way it is. Now it's time to make it actually work.

Everything starts with init(). This is the method that bootstraps the entire notification system, timezone database, plugin, channels, tap callbacks, cold-start handling. It has to run once, before anything else in your app tries to schedule or display a notification. That makes its placement in main.dart critical.

Where init() belongs in your startup sequence

Your main() function is a sequence. Each step depends on the previous one being complete. NotificationService.init() slot belongs after Flutter is initialized, but before your app runs:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final notificationService = NotificationService();
  await notificationService.init();

  runApp(MyApp(notificationService: notificationService));
}

The await is not optional. init() opens the timezone database, makes platform-channel calls to native code, and creates the OS notification channel. None of that is instantaneous. If you forget the await and call runApp while init() is still running, the first scheduling attempt will hit an uninitialized plugin and crash.

WidgetsFlutterBinding.ensureInitialized() must come first because the plugin uses platform channels, and platform channels require the Flutter engine to be fully bootstrapped before they can fire. If you've ever seen the "Binding has not yet been initialized" error, this is what it's protecting against.

Step 1: The timezone setup

The first thing init() does is set up the timezone database. Three lines, three distinct jobs:

Future<void> init() async {
  // Step 1 — Timezone setup
  tz.initializeTimeZones();
  final localTimezone = await FlutterTimezone.getLocalTimezone();
  tz.setLocalLocation(tz.getLocation(localTimezone.identifier));

  // ...
}

tz.initializeTimeZones() loads the entire IANA timezone database into memory. Every timezone on Earth. Every historical DST rule. This runs synchronously and needs to happen before anything else touches timezone-related code.

FlutterTimezone.getLocalTimezone() makes a platform-channel call to the OS and gets back a TimezoneInfo object. We then access its .identifier property to get a string like "Europe/Athens" or "America/New_York". This is async because it crosses the native bridge, even though the OS answers almost instantly, the hop itself is asynchronous.

tz.setLocalLocation(tz.getLocation(localTimezone.identifier)) tells the timezone package: "this is the local zone, treat it as the default when I construct TZDateTime instances." After this line, every TZDateTime.now() call in the app is anchored to the correct local zone.

The order matters. Database first, query device second, set local third. Swap any of them and you'll get cryptic null errors that are painful to trace.

Step 2: Initializing the plugin

Next, we set up flutter_local_notifications with platform-specific settings:

  // Step 2 — Plugin initialization
  const androidSettings = AndroidInitializationSettings('@mipmap/ic_launcher');

  const iosSettings = DarwinInitializationSettings(
    requestAlertPermission: false,
    requestBadgePermission: false,
    requestSoundPermission: false,
  );

  const initSettings = InitializationSettings(
    android: androidSettings,
    iOS: iosSettings,
  );

  await _plugin.initialize(
    settings: initSettings,
    onDidReceiveNotificationResponse: _onTap,
  );

AndroidInitializationSettings takes the name of the notification icon resource. '@mipmap/ic_launcher' points to your app's launcher icon as a fallback. It works, but Android renders it as a white silhouette in the status bar. For production, you'd generate a proper monochrome white icon and reference it as '@drawable/ic_notification'. For our demo, the launcher icon is fine.

DarwinInitializationSettings is the iOS equivalent. Notice all three permission flags are set to false. This is intentional. By default, calling initialize() on iOS would immediately trigger the permission prompt. We don't want that. We want to ask at a moment that makes sense to the user, not blindly at app launch. Setting these flags to false defers the prompt entirely until we explicitly call requestPermissions().

onDidReceiveNotificationResponse: _onTap is where we register our tap callback. When the user taps a notification while the app is running or in the background, the plugin calls _onTap, which pushes the payload into our stream. We'll come back to this in Section 8.

Step 3: Registering channels

Remember the channels enum from Section 5? This is where it earns its place:

  // Step 3 — Register Android channels
  Future<void> _registerChannels() async {
    final androidPlugin = _plugin
        .resolvePlatformSpecificImplementation
            <AndroidFlutterLocalNotificationsPlugin>();

    if (androidPlugin == null) return;

    for (final channel in AppNotificationChannel.values) {
      await androidPlugin.createNotificationChannel(
        AndroidNotificationChannel(
          channel.id,
          channel.name,
          description: channel.description,
          importance: channel.importance,
        ),
      );
    }
  }

resolvePlatformSpecificImplementation returns the Android-specific plugin on Android, and null on iOS. The null check is our platform guard, if we're on iOS, we return immediately. iOS has no channels, so there's nothing to create.

On Android, we iterate every value in AppNotificationChannel and create each one. Adding a new channel in the future means adding one enum value. The registration loop handles it automatically. No code change needed here, ever.

As we noted in Section 4, createNotificationChannel is idempotent. Calling it with an ID that already exists does nothing. So running this on every app launch is completely safe, and it means channels are always in sync with whatever the enum declares.

Step 4: The cold-start scenario

This is the one most tutorials miss entirely, and it's the source of a very specific bug: "I tapped the notification and the app opened, but nothing happened."

Here's what's going on. When the app is completely terminated and the user taps a notification, the OS launches the app fresh. The notification tap happened before our onDidReceiveNotificationResponse callback was even registered, so the plugin catches it separately, holding it for us to retrieve:

  Future<void> _handleLaunchPayload() async {
    final launchDetails = await _plugin.getNotificationAppLaunchDetails();

    if (launchDetails?.didNotificationLaunchApp == true) {
      final payload = launchDetails?.notificationResponse?.payload;
      if (payload != null) {
        WidgetsBinding.instance.addPostFrameCallback((_) {
          _tapPayloads.add(payload);
        });
      }
    }
  }

getNotificationAppLaunchDetails() asks the plugin: "was this app launched by a notification tap?" If yes, we get the payload from the launch details and push it into our stream.

But notice the addPostFrameCallback wrapper. We can't push the payload immediately. At the moment init() runs, the widget tree hasn't been built yet, which means whoever is subscribed to onTap for navigation purposes might not exist yet. By deferring the push to after the first frame is rendered, we guarantee that subscribers are ready to receive the event by the time it arrives.

Without this, cold-start taps would arrive before anything could handle them. The stream would fire into the void. The user would land on the home screen with no indication that the notification wanted to take them somewhere specific.

Putting it all together

Here's the complete init():

Future<void> init() async {
  // 1. Timezone setup
  tz.initializeTimeZones();
  final localTimezone = await FlutterTimezone.getLocalTimezone();
  tz.setLocalLocation(tz.getLocation(localTimezone.identifier));

  // 2. Plugin initialization
  const androidSettings = AndroidInitializationSettings('@mipmap/ic_launcher');
  const iosSettings = DarwinInitializationSettings(
    requestAlertPermission: false,
    requestBadgePermission: false,
    requestSoundPermission: false,
  );
  const initSettings = InitializationSettings(
    android: androidSettings,
    iOS: iosSettings,
  );
  await _plugin.initialize(
    settings: initSettings,
    onDidReceiveNotificationResponse: _onTap,
  );

  // 3. Register channels
  await _registerChannels();

  // 4. Handle cold-start tap
  await _handleLaunchPayload();
}

void _onTap(NotificationResponse response) {
  _tapPayloads.add(response.payload);
}

Read it top to bottom. It flows like a script: prepare the timezone context, wake up the plugin, declare the channels, check if we were launched by a tap. Each step depends only on what came before it. Each step is named clearly enough that you don't need to read the implementation to understand what it does.

That's what good initialization code looks like.

Now the foundation is in place. In the next section, we finally schedule something, and that's where TZDateTime, notification IDs, payloads, and the actual scheduling call all come together.

Section 7: Scheduling, Payloads, and Cancelling

The foundation is in place. Now we write the three methods that make the whole thing actually useful.

Requesting permissions

We covered what these permissions are in Section 3. Here's how you request them at the right moment — when the user takes an action that benefits from notifications, not at app launch:

Future<bool> requestPermissions() async {
    final androidPlugin = _plugin
        .resolvePlatformSpecificImplementation<AndroidFlutterLocalNotificationsPlugin>();

    if (androidPlugin != null) {
      final granted = await androidPlugin.requestNotificationsPermission();
      return granted ?? false;
    }

    final iosPlugin = _plugin
        .resolvePlatformSpecificImplementation<IOSFlutterLocalNotificationsPlugin>();

    if (iosPlugin != null) {
      final granted = await iosPlugin.requestPermissions(
        alert: true,
        badge: true,
        sound: true,
      );
      return granted ?? false;
    }

    return false;
}

The ?? false is important. Some edge cases return null, we treat any non-explicit grant as a denial to be safe. The method returns a bool so the caller can decide what to do next: show an explanation, open Settings, or proceed quietly.

Scheduling a notification

Future<void> scheduleReminder({
  required int id,
  required DateTime fireAt,
  required String title,
  required String body,
  required AppNotificationChannel channel,
  String? payload,
}) async {
  final tzFireAt = tz.TZDateTime.from(fireAt, tz.local);

  final androidDetails = AndroidNotificationDetails(
    channel.id,
    channel.name,
    channelDescription: channel.description,
    importance: channel.importance,
    priority: Priority.high,
  );

  const iosDetails = DarwinNotificationDetails(
    presentAlert: true,
    presentBadge: true,
    presentSound: true,
  );

  await _plugin.zonedSchedule(
    id: id,
    title: title,
    body: body,
    scheduledDate: tzFireAt,
    notificationDetails: NotificationDetails(
      android: androidDetails,
      iOS: iosDetails,
    ),
    payload: payload,
    androidScheduleMode: AndroidScheduleMode.exactAllowWhileIdle,
  );
}

A few things worth highlighting.

tz.TZDateTime.from(fireAt, tz.local) is the conversion we talked about in Section 2. The caller passes a plain DateTime. We convert it internally to a timezone-aware TZDateTime anchored to the device's local zone. The caller never needs to know this happened.

androidScheduleMode: AndroidScheduleMode.exactAllowWhileIdle is the line that connects to USE_EXACT_ALARM from Section 3. It tells Android: fire this alarm at the exact moment specified, even if the device is in deep sleep. Without it, the exact-alarm permission you declared is essentially unused, the alarm would still be inexact.

presentAlert: true on iOS ensures the notification appears as a banner even when the app is in the foreground. Without it, iOS silently suppresses foreground notifications.

One behaviour worth knowing: if you call scheduleReminder with an id that already has a pending notification, the old one is replaced. No duplicates. This makes reschedules effortless, cancel-then-reschedule becomes just reschedule.

The payload and its limits

The payload is a single String? that travels with the notification and comes back to you when the user taps it. It's opaque to the service. We don't open it, we just carry it.

If you need to pass structured data (a screen to navigate to, an item ID, a notification type), encode it as JSON:

final payload = jsonEncode({'route': '/reminder', 'id': '123'});

And decode it when the tap arrives:

final data = jsonDecode(payload) as Map<String, dynamic>;

The hard limit is 4KB for the entire notification payload. That's roughly 4,000 characters, plenty for routing data and IDs, not nearly enough for full objects or images. The right pattern is: send the ID, fetch the data when the user taps. Never try to fit your entire model into a notification payload.

Notification IDs

Every notification needs an int ID. You use it to cancel or replace a specific notification later. The simplest reliable strategy: derive it deterministically from the data you already have.

final id = 'some-unique-key'.hashCode.abs() % 100000;

hashCode gives you a stable integer for any string. abs() removes the possibility of a negative value. % 100000 keeps it in a safe range. The same key always produces the same ID, which means you can always cancel or replace a notification without having stored the ID separately.

Cancelling

Future<void> cancel(int id) async {
  await _plugin.cancel(id: id);
}

Pass the same ID you scheduled with, and the notification disappears from the OS queue. If no notification with that ID exists, this is a no-op. It never throws. Cancel freely.

Next up: the tap. What happens when the user actually presses the notification, and how the stream handles every possible app state.

Section 8: The Tap: Where the Stream Earns Its Keep

We've built the scheduler. Now we need to handle what happens on the other end: the user taps a notification, and your app needs to react. Navigate somewhere. Refresh some data. Show a dialog.

Sounds simple. It isn't. Because the tap can arrive in three completely different situations.

The three app states

The app is open (foreground). The user taps the notification banner. The plugin fires onDidReceiveNotificationResponse immediately. Our _onTap callback picks it up and pushes the payload into the stream.

The app is in the background. Same as foreground. The user taps, the OS brings the app forward, the plugin fires the callback, the stream gets the payload.

The app was completely closed (terminated). The user taps the notification. The OS launches the app fresh. But this time, onDidReceiveNotificationResponse never fires, the callback wasn't registered yet when the tap happened. Instead, the plugin holds the launch payload, and _handleLaunchPayload() (from Section 6) retrieves it after the first frame is rendered and pushes it into the stream.

Three states. Three different paths. One stream that handles all of them the same way.

This is exactly why the stream exists. Without it, you'd need three separate wiring points in your app, each handling the tap slightly differently, each easy to forget. With it, any part of your app subscribes once and receives taps from every state automatically.

How the stream works

A StreamController is a pipe with two ends. The write end is private, only NotificationService can push events into it. The read end is what we expose publicly via the onTap getter:

final StreamController<String?> _tapPayloads =
    StreamController<String?>.broadcast();

Stream<String?> get onTap => _tapPayloads.stream;

The .broadcast() part means multiple listeners can subscribe simultaneously without conflict. Your router subscribes. Your analytics service subscribes. Neither knows the other exists. Both receive the event when a tap arrives.

When _onTap fires (foreground/background) or _handleLaunchPayload runs (terminated), they both do the same thing:

_tapPayloads.add(payload);

One line. The event travels down the stream to every active subscriber.

Subscribing: where and when

Subscribe as early as possible in your app's lifecycle — before any notification could realistically be tapped. main.dart, right after init(), is the right place:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final notificationService = NotificationService();
  await notificationService.init();

  notificationService.onTap.listen((payload) {
    if (payload == null) return;

    final data = jsonDecode(payload) as Map<String, dynamic>;
    final route = data['route'] as String?;

    if (route != null) {
      // Navigate to the right screen based on the route.
      debugPrint('Navigating to: $route');
    }
  });

  runApp(MyApp(notificationService: notificationService));
}

The listen call returns a StreamSubscription. In a real app you'd store this and cancel it on cleanup. In our demo, the service is alive for the app's entire lifetime, so it's fine to let it run.

Notice the addPostFrameCallback from Section 6 handling the terminated case. By the time the post-frame callback fires, main() has already returned, runApp has already built the widget tree, and your listen is already active. The payload arrives to a ready subscriber. The timing is what makes it work.

The full picture

Let's trace a complete notification lifecycle one final time, from scheduling to tap:

User presses the button → scheduleReminder() hands instructions to the OS
10 seconds pass → OS fires the alarm, AlarmManager / UNUserNotificationCenter displays the notification
User taps it → OS invokes the plugin's native callback
Plugin crosses the platform channel back to Dart → _onTap() fires
_onTap() calls _tapPayloads.add(payload) → the stream emits an event
Your listen handler receives the payload → decodes it → navigates

Six steps. Your code only owns steps 1, 4, 5, and 6. Steps 2 and 3 belong entirely to the OS, which is exactly what Section 1 told us from the very beginning.

That's the whole system. From a button press to a tap handler, built on three packages, two platform permissions, one service, and one stream.

Conclusion

And there you have it! What started as a simple "schedule a notification" turned into a full expedition through operating system schedulers, permission layers, notification channels, timezone databases, and stream controllers. I know that's a lot. But every single piece earned its place.

Let's recap what we actually learned. The OS owns the schedule. Your app just hands instructions over and walks away. There are two completely separate permission gates, one that controls whether notifications appear at all, and one that controls whether they appear at the right time. Mixing them up is the root cause of half the notification bugs you'll ever see. A NotificationService that speaks in primitives keeps your notification system reusable across every feature you'll ever build, not just the one that needed reminders today. And a broadcast stream gives every part of your app a unified way to react to taps, regardless of which state the app was in when the user pressed it.

Here's the bigger picture though. Notifications are not a feature. They're infrastructure. And like any infrastructure, the cost of getting them wrong is subtle, a reminder that fires an hour late, a tap that opens the wrong screen, a permission that silently blocks everything on a new Android device. Getting them right doesn't take magic. It just takes understanding what's actually happening underneath the code you write.

The companion repository for this article is available on GitHub. Clone it, run it, and use it as a reference as you build your own implementation.

This was Part 1, local notifications only. Part 2 will cover remote push notifications: how FCM and APNs work, how a server triggers a notification on a user's device, and how you handle the payload when the notification arrives. Everything we built today is the foundation for that. When you understand the local side, the remote side becomes much easier to reason about.

If you enjoyed this article and want to stay connected, feel free to connect with me on LinkedIn.

Was this guide helpful? Consider buying me a coffee! ☕️ Your contribution goes a long way in fuelling future content and projects. Buy Me a Coffee.

As always, go ahead and experiment, dig into the source, and don't be afraid to follow the code wherever it leads. Happy coding, Flutter friends!

The Context Behind the Context: How Flutter Navigation Really Works

Thanasis Traitsis — Mon, 30 Mar 2026 14:37:51 +0000

Have you ever wondered how navigation works in Flutter? I mean, you've typed Navigator.of(context).push(...) dozens of times. It works, you ship it, you move on. But have you ever stopped to ask, how actually does this work? what exactly is context, and why does Navigator need it at all?

This is what we are going to cover in this article. We will explore the navigation system of Flutter and how everything works from the moment you "click" on the button from Screen A, until you land on Screen B. You know me...we will uncover every little secret that is hidden underneath the navigation system. And that's why, we need to start by explaining a few things about the Flutter's Widget Tree in general.

Section 1: The Widget Tree and the others...

Most Flutter developers carry a quiet misconception: that BuildContext is just a handle to their widget. A reference. A fancy this. Well... it isn't. And that misunderstanding is the root cause of some of the most confusing navigation bugs you'll ever encounter.

A Widget in Flutter is immutable. It's a lightweight description of what you want the UI to look like. Cheap to create, cheap to discard. Flutter rebuilds widget trees constantly. But if widgets were the real runtime objects, that would be expensive and lossy.

So Flutter doesn't use them as runtime objects. Instead, it maintains three parallel trees:

The Widget tree: your code. Immutable descriptions.
The Element tree: the live runtime instances. This is where state lives and where BuildContext comes from.
The RenderObject tree: the layout and painting engine.

The most important line in Flutter's source code is this one:

abstract class Element implements BuildContext

Every BuildContext you pass around is an element, NOT a reference to one element. It's the live runtime node, sitting at a specific position in that tree. So we need to be very careful on how we use it.

Context is positional, not global

When your build method receives a BuildContext, Flutter is handing you your element's location in the tree. That location is the key, so we can start our journey looking upwards in the tree:

class MyButton extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // 'context' is this element's position in the tree.
    // Navigator.of() will walk *upward* from here.
    return ElevatedButton(
      onPressed: () => Navigator.of(context).push(...),
      child: const Text('Go'),
    );
  }
}

Navigator.of(context) doesn't search the whole app. It starts at this node and walks up the element tree until it finds a NavigatorState ancestor. The context is the starting point of that walk, which means passing the wrong context, or one from above the Navigator, breaks everything.

This is also why you can't fabricate a context. There's no BuildContext() constructor. It has to be a real, mounted element that exists in the live tree.

Section 2: How Flutter Finds the Navigator

In the previous section, we established that BuildContext is a position in the element tree, and that Navigator.of(context) starts at that position and walks upward looking for a navigation ancestor. Time to make that concrete. What exactly is it looking for, and what happens when it finds it?

When MaterialApp initialises, it quietly inserts a Navigator widget near the top of the tree. Like any StatefulWidget, Navigator is just the blueprint. The real runtime object is its state class: NavigatorState.

NavigatorState is what actually matters. It owns the route stack, the ordered list of screens your user has navigated through, and it exposes the methods you call to manipulate it: push, pop, pushReplacement, and so on. When you call Navigator.of(context), you're not getting the widget. You're getting the NavigatorState.

The ancestor walk

Under the hood, Navigator.of(context) calls a single method on the element:

context.findAncestorStateOfType<NavigatorState>()

This is a linear walk. Starting from the element that owns the context, Flutter climbs the element tree one node at a time, checking each ancestor to see if it holds a NavigatorState. The moment it finds one, it stops and returns it. If it reaches the root without finding one, it throws.

The walk is O(depth), it visits every node between the call site and the Navigator. But this is happening in microseconds so you don't have to worry about any performance issue no matter how "deep" your starting context lives.

What NavigatorState actually owns

Once the walk completes and returns the NavigatorState, you have access to the object that manages your entire navigation history. At its core, NavigatorState maintains two things. The Route Stack and the Overlay Stack. Understanding what each of these does, and how they work together, is exactly what Section 3 is about.

Section 3: The Route Stack, the Overlay, and their communication

Before we jump into the actual Route Stack, we need to talk about what lives inside it. When you call Navigator.of(context).push(...), you don't pass a widget directly. You pass a Route.

child: const Text('Open second screen'),
onPressed: () {
  Navigator.of(context).push(
    MaterialPageRoute<void>( // <---- This one!
      builder: (context) => const SecondScreen(),
    ),
  );
},

A Route is the object that wraps your screen. It carries three things:

the builder that produces your screen's widget tree
the transition animation that plays when the route enters and exits
the settings, things like the route name and any arguments passed to it

Think of it this way: if your screen is an actor, the Route is the contract. It defines when the actor enters, how they enter, and what they bring with them.

The Route Stack

The Route Stack is a plain ordered list of Route objects living inside NavigatorState. The last item in the list is always what the user sees.

push appends to it
pop removes from the end
pushReplacement removes the last item and appends a new one in a single operation

Here's what that list looks like after a typical user journey:

Notice that HomeRoute and ProfileRoute are never destroyed when something is pushed on top of them. They stay mounted in the stack the entire time. This is intentional, it's what makes the back swipe gesture feel instant, and it's what lets you pop back without any rebuild cost.

But be very careful. You don't want to overload your applications with hundreds of Routes. It's perfect when you navigate a couple of screens ahead, but if you use push for every navigation you perform, you will end up with performance issues due to the infinite stacks of routes you keep alive during a session.

The Overlay

The Overlay is NavigatorState's rendering layer. While the Route Stack is the logical list of where you are in the app, the Overlay is the visual layer that actually puts pixels on screen.

Every Route in the stack has a corresponding OverlayEntry, which is a slot in the Overlay that renders that route's widget tree. The Overlay stacks these entries in z-order, so the topmost route in the stack always renders on top of everything else.

This separation is what makes transition animations work. When you push a new route, both the outgoing and incoming routes have active OverlayEntry objects simultaneously. Flutter animates between them at the Overlay level. The old screen slides or fades out while the new one slides or fades in, and only once the animation completes does the old entry become inactive.

What push() actually does

Now we can trace the full picture. When you write this:

Navigator.of(context).push(
  MaterialPageRoute(builder: (_) => const SettingsScreen()),
);

NavigatorState executes five steps in sequence:

The footnote at the bottom is worth highlighting: pop is literally this sequence in reverse. The animation controller plays backwards, the old entry reactivates, and the top route gets removed from _history. No rebuilds, no reconstruction. Just the same entries, animated the other way.

Section 4: Where Context-Based Navigation Breaks Down

Everything we've covered so far assumes one thing: that you have a valid, mounted BuildContext at the exact moment you want to navigate. In simple apps, that assumption holds. In real apps, it breaks. And it breaks in ways that are subtle enough to slip past code review and only surface in production.

There are two situations where Flutter developers hit this wall repeatedly. I am pretty sure that you've been there before, and it's probably one of the reasons you are here reading this blog.

// The broken pattern — seen in both scenarios
class AuthCubit extends Cubit<AuthState> {
  AuthCubit() : super(AuthInitial());

  // Scenario 1: context passed into business logic
  Future<void> login(String email, String password, BuildContext context) async {
    emit(AuthLoading());
    await authRepository.login(email, password); // async gap

    // By the time we resume here, three things may have gone wrong:
    // 1. The widget that passed this context was disposed during the await
    // 2. The element this context points to is now detached from the tree
    // 3. Navigator.of(context) starts a walk from a ghost node — crash
    Navigator.of(context).pushReplacementNamed('/home');
  }
}

// Scenario 2: context passed into a service
class AuthService {
  Future<void> logout(BuildContext context) async {
    await _clearSession();

    // Same problem, this context came from somewhere in the widget tree,
    // but we're now inside a plain Dart class with no lifecycle awareness.
    // There is no 'mounted' check available here. No safety net at all.
    Navigator.of(context).pushNamedAndRemoveUntil('/login', (_) => false);
  }
}

The comments tell the story, but let's make the root cause explicit.

Navigating from a Bloc or a Service

This is the most common one. You have a Cubit handling login. When the login succeeds, you want to navigate to the home screen. The natural instinct is to pass the BuildContext into the cubit and call Navigator.of(context) from inside it.

It feels reasonable. It compiles. And it will eventually crash or misbehave.

The BuildContext is a widget tree concept. It belongs to an element that lives and dies with the widget lifecycle. When you pass it into a Cubit or a Service, you are smuggling a tree-bound object into a layer that has no knowledge of the tree, no lifecycle hooks, and no way to check whether that object is still valid.

At this point, some of you may feel confident. You are like: "What is this guy talking about? Didn't he read the latest news from Flutter release 3.7.0? I can use mounted property because from now on it's accesible from Buildcontext."

class AuthCubit extends Cubit<AuthState> {
  Future<void> login(String email, String password, BuildContext context) async {
    emit(AuthLoading());
    await authRepository.login(email, password); // The Async Gap

    // Yes, Flutter now lets you do this:
    if (context.mounted) {
       Navigator.of(context).pushReplacementNamed('/home');
    }
  }
}

If you think that if (context.mounted) is the perfect solution, you are wrong. And there are a few reasons why you shouldn'y use this approach:

Tight Coupling: Your AuthCubit is now impossible to unit test without mocking the entire Flutter framework. You’ve successfully welded your business logic to your widget tree.
The "Wrong House" Problem: A Cubit is often shared. If you pass a context from Screen A, but the user has already navigated to Screen B, context.mounted might still be true, but you’re now performing navigation logic from a "stale" location in the background.
Lifecycle Ignorance: A Cubit or a Service class doesn't know about the Widget's lifecycle. It doesn't know why a widget was unmounted. By the time your await finishes, the entire navigation intent might be irrelevant, but your service is still trying to drive the car.

To sum up, the BuildContext is a "handle" for the Element Tree. It belongs to the View. When you pass it into a Cubit or a Service, you aren't just passing an object, you're leaking a dependency.

Section 5: The NavigationService Pattern

Everything in the previous section points to the same conclusion: the problem isn't your code, it's the dependency. As long as navigation requires a BuildContext → it requires a live element → which requires a mounted widget → which requires being inside the widget lifecycle. Break any link in that chain and navigation breaks with it.
The NavigationService pattern severs that dependency entirely. Instead of walking the element tree to find NavigatorState, you hold a permanent direct reference to it, one that is valid for the entire lifetime of the app, not just the lifetime of a widget.

The GlobalKey: a reference that survives the tree

A GlobalKey<NavigatorState> is Flutter's mechanism for holding a stable reference to a specific State object across the entire app. Unlike a BuildContext, which is tied to an element's position in the tree, a GlobalKey is registered in a global registry the moment its associated widget is mounted, and it stays there until the widget is permanently removed. What this means in practice: navigatorKey.currentState gives you direct access to the NavigatorState at any time, from anywhere in your codebase. No walk. No context. No lifecycle dependency. As long as MaterialApp is in the tree (which is always, for a running app), the key is valid.

This is the mechanical reason the pattern works. It's not a workaround or a hack, it's using a first-class Flutter API exactly as it was designed to be used. Let's look at the code:

Building the NavigationService

The NavigationService is straightforward. It's a singleton that wraps the key and exposes clean navigation methods:

class NavigationService {
  NavigationService._internal();
  static final NavigationService instance = NavigationService._internal();

  final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

  NavigatorState get _navigator => navigatorKey.currentState!;

  Future<dynamic> push(Widget screen) {
    return _navigator.push(
      MaterialPageRoute(builder: (_) => screen),
    );
  }

  // implement pushReplacement, pushNamed, pushNamedAndRemoveUntil and everything else
}

MaterialApp

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: NavigationService.instance.navigatorKey,
      initialRoute: '/home',
      routes: {
        '/home': (_) => const HomeScreen(),
        '/login': (_) => const LoginScreen(),
        '/profile': (_) => const ProfileScreen(),
      },
    );
  }
}

As you can see, we set our GlobalKey into our MaterialApp, and we are good to go. All we have to do right now, is use our NavigationService for every navigation we want to execute in our app. Nothing will break, nothing will crash, and there is no need to search all the ancestors until you reach this destination.

Simple Cubit Example

class AuthCubit extends Cubit<AuthState> {
  AuthCubit({required AuthRepository authRepository})
      : _authRepository = authRepository,
        super(AuthInitial());

  final AuthRepository _authRepository;

  Future<void> login(String email, String password) async {
    emit(AuthLoading());
    await _authRepository.login(email, password);

    // Direct call — always safe, no mounted check needed
    NavigationService.instance.pushNamedAndRemoveUntil('/home');
  }

  Future<void> logout() async {
    await _authRepository.logout();
    NavigationService.instance.pushNamedAndRemoveUntil('/login');
  }
}

With the NavigationService in place, your architecture has a clean separation: widgets own the element tree, business logic owns state, services own data, and navigation is a shared utility that any layer can call without crossing into another layer's territory.

Conclusion

And there you have it! What started as a simple Navigator.of(context).push(...) turned into a full expedition through Flutter's internals. I know that we usually don't really care about all these things we use in our everyday-code. We just type 2-3 lines that we know, we see that it works, and we move on. But this topic felt really interesting to me and I believe you can benefit a lot by searching through its core.

So... what did we learn today? We learned that BuildContext is not just a reference to your widget, it's a live node in the element tree, with a position, a lifetime, and a very specific job. We traced how Navigator.of(context) walks that tree upward, node by node, until it finds a NavigatorState to grab onto. We opened up NavigatorState itself and saw the two things it owns (the Route Stack and the Overlay) and we watched exactly how a single push() call mutates both of them in five precise steps.

And finally, we saw where the context-based approach hits its limits, and how a NavigationService backed by a GlobalKey lets you navigate from anywhere in your app. More importantly, we didn't just learn how to navigate. We learned why it works the way it does. And that's the kind of understanding that sticks, the kind that makes the next confusing bug a little less mysterious, and the next architecture decision a little more confident.

One last thing, we didn't cover go_router in this article, and that was intentional. This was about the "what" and the "how" underneath the hood. But if you're starting a new Flutter app, go_router is absolutely worth your time. It's the recommended routing solution in the Flutter documentation for a reason, and once you use it, you can't go back.

If you enjoyed this article and want to stay connected, feel free to connect with me on LinkedIn.

Was this guide helpful? Consider buying me a coffee!☕️ Your contribution goes a long way in fuelling future content and projects. Buy Me a Coffee.

As always, go ahead and experiment, dig into the framework source, and don't be afraid to follow the code wherever it leads. Happy coding, Flutter friends!

Flutter App Taking Too Long to Start? Here's What You're Doing Wrong

Thanasis Traitsis — Fri, 27 Feb 2026 07:27:45 +0000

If you've ever launched your app and stared at a white screen for what feels like an eternity before anything shows up, you're not alone. I've been there too. Recently, while working on a project that had grown quite a bit in complexity, I noticed that the startup time had become... let's say, uncomfortably long. The splash screen wasn't even getting a chance to say hello before the app had already made a bad first impression. That's when I realized I had a problem, and more importantly, that I had been thinking about app initialization the wrong way.

So in this article, we're going to fix that. We'll go through 7 practical tips that will help you dramatically reduce your Flutter app's startup time, eliminate that white screen, and give your users the smooth, snappy experience they deserve. Some of these are quick wins, others require a small shift in how you think about your app's startup flow. But all of them are worth it.

1. Move Heavy Work After runApp()

This is the most important one. You can skip the rest of the article and move on with your life after reading this (please don't). The root of most startup performance problems in Flutter comes down to a single habit: loading everything before calling runApp().

Think about what happens when your app launches. Flutter needs to paint the first frame on the screen as fast as possible. But if your main() function is busy initializing databases, fetching remote configs, setting up services, and registering half the universe before runApp() even gets called, Flutter has no choice but to wait. And while it waits... your user stares at a white screen.

The fix? Be ruthless about what truly needs to be ready before the first frame.

Ask yourself this question for every single thing you initialize: "Will the app crash or look broken without this on the very first frame?" If the answer is no, it doesn't belong before runApp().

In reality, the list of things that genuinely need to be ready before runApp() is much shorter than most people think. Here's what actually makes the cut:

Theme → your app needs to know which colors and fonts to use from the very first pixel
Language/Locale → same idea, the UI needs to know which language to render immediately
Authentication state → you need to know if the user is logged in or not before deciding which screen to show first

That's pretty much it. Everything else, your analytics setup, your remote config, your ad services, your connectivity listeners, can wait. Initialize them after runApp(), in the background, while your user is already looking at something real.

2. Compress Your Assets

Are you still here? Great! This one is a quick win that most developers completely overlook. While you're focusing on the code side of initialization, your assets might be quietly working against you behind the scenes.

Think about your splash screen image. It's the very first visual your app needs to load, so if that image is a 2MB PNG that Flutter has to decode before painting anything, you've already lost precious milliseconds before the user sees a single pixel. The same goes for any font files or images that are part of your initial UI.

The fix here is simple: compress everything that gets loaded at startup.

For images, tools like TinyPNG or Squoosh can reduce file sizes dramatically, often by 60-80%, with little to no visible quality difference. For your splash screen specifically, consider using a simple vector image (SVG) or even a plain color with your logo instead of a heavy raster image. Flutter's native splash screen supports this out of the box and it's blazing fast.

For fonts, make sure you're only bundling the font weights you actually use. It's very easy to include an entire font family with 10 different weights when your app only uses 2 of them. Every unnecessary file is extra work Flutter has to do before your app feels alive.

A good rule of thumb: anything that gets loaded before or during your splash screen should be as lightweight as possible. Your goal is to make Flutter's job as easy as it can be in those critical first moments.

3. Show a Screen Immediately, Load the Real App Behind the Scenes

Here's the idea behind this one. Instead of making the user wait until every single thing is ready before showing anything, you show a simple screen instantly and then load the real app behind the scenes. By the time the user has registered what they're looking at, your app is already done initializing.

Think of it like a restaurant. A good waiter doesn't make you stand outside until your table is fully set, the food is cooked, and the wine is poured. They seat you immediately, hand you the menu, and let the kitchen do its thing in the background. You're already inside, you're comfortable, and everything else arrives naturally.

In Flutter, this pattern looks something like this:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Load only the essential data
  await setupEssentialServices();

  runApp(const AppLoader());
}

AppLoader is not your real MaterialApp. It's a lightweight widget that shows something instantly, maybe your splash screen or a simple branded loading screen, while the rest of your services finish initializing in the background. Once everything is ready, you swap it out for your real MaterialApp.

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

  @override
  State<AppLoader> createState() => _AppLoaderState();
}

class _AppLoaderState extends State<AppLoader> {
  bool _isReady = false;

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

  Future<void> _loadRemainingServices() async {
    await setupRemainingServices();
    setState(() => _isReady = true);
  }

  @override
  Widget build(BuildContext context) {
    if (!_isReady) {
      return const MaterialApp(
        home: SplashScreen(),
      );
    }

    return const RealApp();
  }
}

The beauty of this approach is that your user never sees a white screen. They land on your splash screen almost instantly, and by the time they're done admiring your beautiful logo, the app is fully ready to go.

4. Use compute() for Heavy Work

Let's talk about something that trips up a lot of Flutter developers: the UI thread. Flutter runs everything, your widgets, your animations, your build methods, on a single thread called the main isolate. Think of it as a single chef in a kitchen. As long as the orders are small and simple, everything runs smoothly. But the moment you ask that chef to also butcher a whole cow, debone a fish, and bake a soufflé at the same time, the orders start piling up and the whole kitchen grinds to a halt.

In Flutter terms, that "grinding to a halt" is what we call jank. Dropped frames, frozen animations, an unresponsive UI. And it often happens right at startup, when you're doing things like parsing a large JSON response, processing a big list of data, or running some heavy computation to set up your initial app state. So what's the solution?

Dart actually supports multiple isolates, which are independent threads of execution that don't share memory with each other. Think of it as hiring a second chef who works in a completely separate kitchen. They can handle the heavy lifting without ever interfering with the main kitchen's flow.

This is exactly where compute() comes in. It's Flutter's friendly wrapper around isolates that makes the whole thing approachable. You simply hand it a function and some data, it spins up a separate isolate, runs your function there, and hands you back the result. The main thread never feels a thing.

// A top-level or static function (required for compute)
List<WordModel> parseWords(String jsonString) {
  final decoded = jsonDecode(jsonString) as List;
  return decoded.map((e) => WordModel.fromJson(e)).toList();
}

// Using compute() to run it off the main thread
final words = await compute(parseWords, rawJsonString);

Notice that the function you pass to compute() must be a top-level or static function. This is because isolates don't share memory, so the function needs to be accessible without any context from the main isolate.
When should you actually use this?

Not everything needs compute(). Spinning up an isolate has its own small overhead, so using it for trivial work would actually make things slower. A good rule of thumb is to reach for compute() when:

You're parsing a large JSON file or dataset
You're doing heavy string manipulation or encryption
You're processing images or running complex algorithms
Any operation that takes more than a few milliseconds and makes your UI feel laggy

For anything quick and lightweight, just run it normally on the main thread. The chef can handle a simple sandwich without any help.

5. Use Lazy Loading for Your Dependencies

Let's talk about dependency injection and a mistake that's very easy to make without even realizing it. When you set up your app's services and dependencies at startup, there's a natural temptation to initialize everything upfront. It feels organized, it feels safe, it feels like you're in control. But here's the problem: most of those services won't be needed until much later in the app's lifecycle. Some of them might not even be needed at all during a particular session.

Initializing a service means allocating memory, running setup code, and sometimes even making network calls or reading from disk. If you're doing all of that for 15 different services before your app even shows the first screen, you're essentially paying a cost you don't need to pay yet. This is where lazy loading comes in.

The idea is simple: instead of initializing a service immediately when you register it, you tell your app "create this only when someone actually asks for it for the first time." Until that moment, it doesn't exist, it doesn't consume memory, and it doesn't slow down your startup. The difference looks something like this:

// Eager initialization — created immediately, whether you need it or not
final analyticsService = AnalyticsService();

// Lazy initialization — created only when first accessed
AnalyticsService? _analyticsService;
AnalyticsService get analyticsService {
  _analyticsService ??= AnalyticsService();
  return _analyticsService!;
}

It's a small change in how you think about your dependencies, but the impact on startup time can be significant, especially as your app grows and the number of services increases.

6. Use Future.wait() for Parallel Async Work

Alright, this one is all about efficiency. Let's say you have 3 services that need to be initialized at startup. The most natural way to write this is:

await initializeTheme();
await initializeLanguage();
await initializeAuth();

This looks clean and readable. But here's the problem: these three operations run sequentially. One after the other. initializeLanguage() doesn't even start until initializeTheme() is completely done. And initializeAuth() sits there waiting for both of them to finish before it even gets to wake up.

Cooking references are never enough... Imagine you need to boil three separate pots of water. The sequential approach would be: boil the first pot, wait until it's done, then start the second pot, wait until it's done, then start the third. That's... not how anyone actually cooks. You put all three pots on the stove at the same time and let them all boil together. Future.wait() is exactly that. It takes a list of futures and runs them all at the same time, then waits until every single one of them is done before moving forward.

await Future.wait([
  initializeTheme(),
  initializeLanguage(),
  initializeAuth(),
]);

The total time is now determined by the slowest operation, not the sum of all of them. If each operation takes 300ms sequentially that's 900ms total. With Future.wait(), it's just 300ms. That's a 3x improvement with a one-line change

But wait, when can you actually use this?

This is the important part that a lot of articles skip over. Future.wait() is not a magic wand you can wave over every initialization call. It only works safely when your services are completely independent of each other. Think about it. If initializeAuth() needs the result of initializeDatabase() to do its job, you can't run them in parallel. Auth would try to use a database that isn't ready yet and everything would fall apart.

It's a very powerful tool, but it needs to be used thoughtfully!

7. Avoid Synchronous Work in main()

We've talked a lot about async operations so far, but there's another category of startup killers that's even more sneaky: synchronous work.

Here's why it's sneaky. When you await something async, Flutter at least has the opportunity to do other things while it waits. But synchronous code is different. It runs from start to finish without ever letting go of the thread. No pauses, no breaks, no mercy. The UI thread is completely blocked until every last line is done.

void main() {

  final config = File('config.json').readAsStringSync(); // Synchronous file read
  final decoded = jsonDecode(config); // Heavy JSON parsing
  final settings = processSettings(decoded); // Complex computation

  runApp(MyApp());
}

Every one of those lines is holding the UI thread hostage. Flutter cannot paint a single pixel until all of that is done. The user sees white. The rule here is simple: if it's heavy and it's synchronous, it has no business being in main().

The solution depends on what the work actually is:

If it's I/O work: (reading files, accessing disk), swap the synchronous version for its async counterpart:

// Blocks the thread completely
final config = File('config.json').readAsStringSync();

// Frees the thread while waiting
final config = await File('config.json').readAsString();

If it's heavy computation (parsing, processing, transforming data), this is exactly the case for compute() that we covered in Tip #4. Ship it off to a separate isolate and let the main thread breathe:

// Heavy parsing blocking the main thread
final settings = parseHeavyConfig(rawData);

// Same work, different thread
final settings = await compute(parseHeavyConfig, rawData);

Your main() function should be lean, fast, and humble. It should do the minimum amount of work needed to get something on the screen, and then get out of the way.

Conclusion

There you have it, my friends! Seven practical tips that can completely transform the way your app feels from the moment it launches. Let's do a quick recap of everything we covered:

Move heavy work after runApp() — be ruthless about what truly needs to be ready before the first frame
Compress your assets — don't let a heavy splash screen image undo all your hard work
Show a screen immediately — perceived performance is just as important as real performance
Use compute() for heavy work — stop blocking the UI thread and let isolates do the heavy lifting
Use lazy loading for your dependencies — don't pay for services you're not using yet
Use Future.wait() for parallel async work — stop waiting in line when you can run everything at the same time
Avoid synchronous work in main() — synchronous code is a silent killer that blocks the thread completely

Here's the bigger picture though. All seven of these tips share the same underlying philosophy. Your app should do the minimum amount of work needed to show something to the user as fast as possible, and defer everything else. Once you start thinking that way, you'll naturally write faster, more efficient Flutter apps without even trying. The white screen is not inevitable. It's a symptom of not prioritizing what truly matters at startup. And now that you know better, you can fix it.

If you enjoyed this article and want to stay connected, feel free to connect with me on LinkedIn.

Was this guide helpful? Consider buying me a coffee!☕️ Your contribution goes a long way in fuelling future content and projects. Buy Me a Coffee.

Flutter Sticky Bottom Button: Beyond the FloatingActionButton

Thanasis Traitsis — Wed, 18 Feb 2026 23:05:32 +0000

Flutter gives us the FloatingActionButton, and don’t get me wrong, it’s great.

But sometimes… it’s just not enough.

Sometimes we want more control over how and when a button appears. Maybe we want it to stick to the bottom of the screen only for a specific section. And when we finally reach the bottom of that section, we want it to stay there, in its natural position, without floating awkwardly above the content.

There are countless scenarios where this behavior makes sense. I won’t limit your imagination with just one. Today, I’ll show you how to create a smart sticky button, one that stays pinned exactly as long as you want it to. And more importantly, we’re not just going to build it. We’re going to understand every single detail behind it. By the end of this article, you’ll be able to take this pattern and adapt it to anything you need. Let’s begin.

What we are going to build

Before we dive into the code, let’s first see the final result. Here's a preview:

What exactly is going on here:

When the button is visible in its natural position → nothing special happens.
As soon as you scroll and the button moves off screen → it smoothly pins itself to the bottom.
When you scroll back down and reach the button’s original position → the pinned version disappears and the inline one takes over again.

No layout shifts. No jumpy behavior. No weird overlap.

And the best part? We’re not using any external packages. We will use all the available tools from Flutter. We need Stack, ScrollController and GlobalKey together with some math. Enough with the preview, let's get to the coding part!

How to build this actually?

Before we make anything sticky, we need a normal screen. Just a simple scrollable layout with a button at the bottom.

Here’s our starting point:

import 'package:flutter/material.dart';

void main() {
  runApp(const MainApp());
}

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

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      debugShowCheckedModeBanner: false,
      home: HomePage(),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Pinned Bottom Button')),
      body: SafeArea(
        child: SingleChildScrollView(
          padding: const EdgeInsets.all(8),
          child: Column(
            children: [
              Column(
                spacing: 12,
                children: List.generate(
                  20,
                  (index) => Container(
                    width: double.infinity,
                    padding: const EdgeInsets.symmetric(
                      horizontal: 20,
                      vertical: 12,
                    ),
                    decoration: BoxDecoration(
                      color: const Color.fromARGB(255, 205, 206, 207),
                      borderRadius: BorderRadius.circular(8),
                      border: Border.all(width: 1, color: Colors.black),
                    ),
                    child: Text(
                      "Random List Item $index",
                      style: const TextStyle(
                        fontSize: 16,
                        fontWeight: FontWeight.bold,
                      ),
                    ),
                  ),
                ),
              ),
              const SizedBox(height: 16),
              SizedBox(
                width: double.infinity,
                child: ElevatedButton(
                  onPressed: () {},
                  child: const Text("Pinned Button"),
                ),
              ),
              const SizedBox(height: 16),
              const Text("Random content at the bottom of the page."),
            ],
          ),
        ),
      ),
    );
  }
}

What Do We Have So Far?

Let’s break this down. We have:

A SingleChildScrollView
A Column with dummy content
A button placed naturally at the bottom
Some extra content after the button

Right now, the button behaves normally. If you scroll up, it disappears. If you scroll down, you see it again.

There is nothing “sticky” about it.

Introduce the StatefulWidget

Right now, our screen is a StatelessWidget. And that makes sense, until we realize something important. We want the UI to react to scroll changes. The moment we say “react”, we introduce state.

Our button visibility will depend on:

Whether the screen is scrollable
Where the inline button currently is
Whether it reached the fixed bottom position

All of those values change over time. And when something changes over time in Flutter… we need a StatefulWidget. With that change, we get access to important methods like initState(). Let's see how we use them:

class _HomePageState extends State<HomePage> {
  final ScrollController _scrollController = ScrollController();

  bool _isScrollable = false;

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

    _scrollController.addListener(_onScroll);

    WidgetsBinding.instance.addPostFrameCallback((_) {
      _checkIfScrollable();
    });
  }

  void _checkIfScrollable() {
    if (!_scrollController.hasClients) return;

    final isScrollable = _scrollController.position.maxScrollExtent > 0;

    setState(() {
      _isScrollable = isScrollable;
    });

    if (isScrollable) {
      WidgetsBinding.instance.addPostFrameCallback((_) {
        _updateButtonVisibility();
      });
    }
  }

  void _onScroll() {
    if (!_isScrollable) return;

    WidgetsBinding.instance.addPostFrameCallback((_) {
      _updateButtonVisibility();
    });
  }

Why we need ScrollController?

With the SingleChildScrollView we apply the scrolling functionality to our screen. By default, we have no idea when it actually scrolls. So, here comes the ScrollController!

SingleChildScrollView(
  controller: _scrollController,

Now, we have access to the scroll position, we listen to scrolls and we also have the information about how much content exceeds the screen. As you can see, this controller acts as the communication bridge between the scrollable widget and our state logic. And this line is where things become reactive:

_scrollController.addListener(_onScroll);

Every time the scroll position changes, _onScroll() gets called.

The importance of initState()

initState() runs exactly once, when the widget is inserted into the widget tree. This makes it the perfect place to:

Attach listeners
Initialize controllers
Perform one-time setup logic

We never attach listeners inside build(). Why? Because build() can run many times. Think of all the "noise" we would have if we attached a listener everytime the build() was triggered.

Why Use addPostFrameCallback?

If you see inside initState(), we have:

WidgetsBinding.instance.addPostFrameCallback((_) {
  _checkIfScrollable();
});

Why don't we just call _checkIfScrollable() directly? Because when initState() runs, the UI has not been laid out yet. At that moment:

The scroll view doesn’t know its dimensions
The content hasn’t been measured
maxScrollExtent is not reliable

If we check scroll metrics too early, we might get incorrect values. But, addPostFrameCallback runs after the first frame is rendered. This guarantees that our logic runs at the correct time.

Also, it's important to explain one more critical part of the code. Inside _checkIfScrollable(), we calculate:

final isScrollable = _scrollController.position.maxScrollExtent > 0;

maxScrollExtent represents:

The total scrollable distance beyond the visible viewport.

If it equals 0:

The content fits entirely on the screen.
There is nothing to scroll.
Sticky behavior is unnecessary.

If it’s greater than 0:

The content exceeds the screen height.
The screen is scrollable.
Our sticky logic becomes relevant.

So _isScrollable acts as a guard. If the screen isn’t scrollable, we don’t waste time calculating button positions. It's a small optimization, but important. This is what makes the difference in the code afterall.

Let's add the Sticky button

What do we have so far? Right now, we have a button that lives inside our SingleChildScrollView, but we need a button that will flow above all content. This functionality gets unlocked by wrapping our entire content into a Stack. Stack is a very powerful Widget in Flutter that lets multiple layers of content get on top of each-other. And this is exactly what we need here:

body: SafeArea(
  child: Stack(
    children: [
      SingleChildScrollView(
        controller: _scrollController,
        padding: const EdgeInsets.all(8),
        child: Column(
          children: [
            // Scrollable content
            SizedBox(
              key: _inlineButtonKey,
              width: double.infinity,
              child: Opacity(
                opacity: _inlineOpacity,
                child: _buildButton(),
                ),
            ),
          ],
        ),
      ),

      Positioned(
        left: 8,
        right: 8,
        bottom: 16,
        child: Opacity(
          key: _floatingButtonKey,
          opacity: _floatingOpacity,
          child: IgnorePointer(
            ignoring: _floatingOpacity == 0.0,
            child: _buildButton(),
          ),
        ),
      ),
    ],
  ),
),

  Widget _buildButton() {
    return ElevatedButton(
      onPressed: () {},
      style: ElevatedButton.styleFrom(
        padding: const EdgeInsets.all(12),
        backgroundColor: const Color(0xFFD97757),
        shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(8)),
      ),
      child: const Text(
        "Pinned Button",
        style: TextStyle(
          color: Colors.white,
          fontSize: 18,
          fontWeight: FontWeight.bold,
        ),
      ),
    );
  }

We use the same button for both the floating button and our inline button, so it's better if we create a separate Widget to stay aligned in both cases. But now there are a lot of new interesting things inside the code. Why do we need keys? How do we use opacity? Let's explain everything!

Why Do We Need GlobalKey?

final GlobalKey _inlineButtonKey = GlobalKey();
final GlobalKey _floatingButtonKey = GlobalKey();

We attach two GlobalKeys to our two button widgets because this gives us access to their underlying RenderObject. Normally in Flutter, we don’t go that deep. We declare widgets, Flutter lays them out, and that’s it.

But in this case, we need something very specific:

We need to know the exact position of these buttons on the screen. And that information is not available at the widget level. It lives inside the rendering layer. More specifically, inside the widget’s RenderObject. That’s why we need a GlobalKey.

How Do We Access the Exact Location of the Buttons?

Earlier, we referenced a method called _updateButtonVisibility(). Now it’s time to take a closer look at it:

  void _updateButtonVisibility() {
    final inlineBox =
        _inlineButtonKey.currentContext?.findRenderObject() as RenderBox?;
    final floatingBox =
        _floatingButtonKey.currentContext?.findRenderObject() as RenderBox?;

    if (inlineBox == null || floatingBox == null) return;

    final inlinePosition = inlineBox.localToGlobal(Offset.zero).dy;
    final floatingPosition = floatingBox.localToGlobal(Offset.zero).dy;

    final reachedFixedPosition = inlinePosition <= floatingPosition;

    setState(() {
      if (reachedFixedPosition) {
        _inlineOpacity = 1.0;
        _floatingOpacity = 0.0;
      } else {
        _inlineOpacity = 0.0;
        _floatingOpacity = 1.0;
      }
    });
  }

The key part of this method, is here:

    final inlinePosition = inlineBox.localToGlobal(Offset.zero).dy;
    final floatingPosition = floatingBox.localToGlobal(Offset.zero).dy;

Let's break down what's going on here. First of all, we use Offset.zero. That represents the top-left corner of the widget in its local coordinate system, which will be our target-point.

Offset(0,0)

By default, a widget’s position is relative to its parent. That means if we just queried its layout position normally, we would get coordinates relative to the parent widget, not the screen.

But we don’t care about the parent. We care about the screen. localToGlobal() converts a local coordinate into a global screen coordinate.

Offset(24.0, 612.0)

This means:

24 pixels from the left side of the screen
612 pixels from the top of the screen

From that Offset, we only care about the vertical position, so we extract the dy. And the final result looks like this:

inlinePosition = 612.0

The logic behind this calculation

The entire purpose of measuring these two positions is very simple. We want to know when both buttons are aligned vertically.
Let’s think about their behavior:

The inline button lives inside the scroll view → its Y position constantly changes while scrolling.
The floating button is positioned using Positioned(bottom: 16) → its Y position remains stable.

As we scroll upward:

The inline button moves closer to the floating button’s position.
Its .dy value decreases.

The moment this becomes true:

inlinePosition <= floatingPosition

It means:

The top-left corner of the inline button has reached (or passed) the top-left corner of the floating button. At that exact moment, the two buttons are aligned. And that’s when we switch visibility.

The inline button takes over. The floating button disappears.

Opacity toggle

Inside setState() we change the opacity between the two buttons. Only one of them can be visible. But why is it so important to use Opacity and we didn't choose to remove the unsused Widget? The reason is to avoid UI leaks. If we add/remove Widgets all the time, we may
change layout height, cause visual jumps, or more importantly affect scroll position. Opacity keeps layout stable.

Conclusion

And there you go! What started as a simple scrollable screen slowly evolved into a fully controlled sticky button pattern, built entirely with Flutter’s core tools. No packages. No hacks. Just a solid understanding of how layout, scrolling, and rendering work together.

Along the way, we didn’t just “make a button stick.” We explored StatefulWidget, ScrollController, addPostFrameCallback, GlobalKey and more. This pattern might not be something you implement every day. But when you need precise scroll-aware behavior, (like checkout CTAs, smart action bars, or contextual buttons) understanding this technique gives you full control.

Hopefully, this guide didn’t just show you how to build a sticky button, but helped you better understand how Flutter thinks about layout and positioning.

If you enjoyed this article and want to stay connected, feel free to connect with me on LinkedIn.

If you'd like to dive deeper into the code and contribute to the project, visit the repository on GitHub.

Was this guide helpful? Consider buying me a coffee!☕️ Your contribution goes a long way in fuelling future content and projects. Buy Me a Coffee.

Now go ahead. Play with it. Improve it. And we will catch up in the next blog!

Creating Spotlight Tutorials in Flutter: The Complete Guide to Selective Overlays

Thanasis Traitsis — Sun, 11 Jan 2026 11:10:11 +0000

Hello there, my Flutter friends! Recently, I downloaded an app and, when I opened it for the first time, I noticed this cool feature that many apps use to guide new users through their core functionality. You know what I am talking about: a button gets highlighted, the rest of the screen fades out, and your attention is drawn exactly where the developer wants it to be. This kind of spotlight onboarding is everywhere, and that’s when I had my “Eureka” moment!

That’s what this blog is all about. We’ll build this exact effect in Flutter, step by step, and use it as an opportunity to deeply understand how Flutter handles rendering, painting, and widget positioning under the hood.

The UI Setup

I want to keep the UI as simple as possible. We’ll start with a clean home screen that contains just a few buttons. The ones we’re going to highlight, and one extra button that will trigger the highlight effect. Yes, we’ll manually turn the effect on and off. You don’t expect me to build a full onboarding system from scratch… do you? You can find all the code you need from the github repository at the end of this article.

The Highlight Effect

Now it’s time for the interesting part. How do we "remove" the color from the entire screen, while keeping specific widgets fully visible? The answer is simple: we don’t remove anything. Instead, we are going to add something on top.

To achieve this effect, we introduce an extra layer that sits above our existing UI. This layer acts as a semi-transparent overlay, covering the whole screen and dimming everything underneath. The key trick, however, is that this overlay is not solid. We intentionally “cut out” specific areas that line up with the widgets we want to highlight.

How does this effect work?

We add a full-screen overlay on top of our screen and paint it with a dark color and some opacity. This allows the underlying UI to remain visible, but visually de-emphasized. Then, for each widget we want to spotlight, we carve a transparent hole in that overlay, positioned exactly where the widget appears on the screen.

As a result:

The background content fades into the dark overlay
The highlighted widgets remain completely clear and untouched
The user’s attention is naturally drawn to the important elements

Nothing from the original UI is modified or removed. The entire effect is purely visual and lives in its own layer, which makes it both powerful and flexible. Now that we have a clear picture of what we want to achieve, it’s time to start building it.

The Overlay Layer

Before we dive into anything fancy, we need a solid foundation. The first step is to create a reusable screen widget that we can use across the app. Nothing special here, just a simple Scaffold with some padding and a SafeArea to keep things clean.

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
        child: Padding(
          padding: const EdgeInsets.symmetric(horizontal: 16),
          child: child,
        ),
      ),
    );
  }

At this point, we have a perfectly normal screen. Now comes the important question:
How do we place something on top of it without touching the existing UI?

This is where the Stack widget comes in. Stack lets us layer widgets on top of each other (like layers in Photoshop). The first child is the bottom layer, subsequent children stack on top. Here’s how our updated CustomScreen looks:

class CustomScreen extends StatelessWidget {
  final Widget child;
  final bool showOverlay;
  final List<GlobalKey>? highlightWidgetKeys;
  final VoidCallback? onOverlayTap;
  final HighlightStyle? highlightStyle;

  const CustomScreen({
    super.key,
    required this.child,
    this.showOverlay = false,
    this.highlightWidgetKeys,
    this.onOverlayTap,
    this.highlightStyle,
  });

  bool get _shouldShowOverlay =>
      showOverlay &&
      highlightWidgetKeys != null &&
      highlightWidgetKeys!.isNotEmpty;

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        Scaffold(
          body: SafeArea(
            child: Padding(
              padding: const EdgeInsets.symmetric(horizontal: 16),
              child: child,
            ),
          ),
        ),
        if (_shouldShowOverlay)
          Positioned.fill(
            child: _SelectiveOverlay(
              widgetKeys: highlightWidgetKeys!,
              onDarkAreaTap: onOverlayTap,
              style: highlightStyle ?? const HighlightStyle(),
            ),
          ),
      ],
    );
  }
}

A few important things are happening here:

The Stack allows us to layer widgets on top of each other
The Scaffold remains untouched and behaves exactly as before
The overlay is rendered only when needed, controlled by _shouldShowOverlay
Positioned.fill ensures the overlay covers the entire screen

Now, let’s look at some of the more interesting parts of this implementation.

Highlighting specific widgets

You’ll notice that we pass a variable called highlightWidgetKeys. This is a list of GlobalKeys that correspond to the widgets we want to highlight. Since we may want to spotlight more than one widget at a time, we use a List.

Why GlobalKeys?
GlobalKeys are special identifiers in Flutter that let us access a widget's RenderObject (the actual painted object on screen) and its position. Without them, we couldn't know where to "cut holes" in the overlay. You can check the detailed documentation here.

Styling the highlights

You’ll also notice that we pass a HighlightStyle object into our overlay. This is a small but important design choice.

Instead of hardcoding colors, padding, and border radius inside our rendering logic, we extract all styling concerns into a dedicated class. This keeps our code clean, reusable, and much easier to maintain.

class HighlightStyle extends Equatable {
  final Color overlayColor;
  final double borderRadius;
  final double padding;

  const HighlightStyle({
    this.overlayColor = Colors.black54, // Opacity for the overlay layer
    this.borderRadius = 12.0, // Rounded corners for highlighted areas
    this.padding = 8.0, // Extra spacing around highlighted widgets
  });

  @override
  List<Object?> get props => [overlayColor, borderRadius, padding];
}

At this stage, we’re not drawing anything yet. We’re simply preparing the screen to host a visual layer that can sit above the UI and react to user interactions independently.

In the next section, we’ll see how this overlay actually draws itself and how it knows where to create those transparent “holes” on the screen.

How does Flutter go from widgets to pixels?

Before we dive into the nitty-gritty of custom painting and hit testing, we need to understand an important bridge in Flutter's architecture. You see, Flutter has a beautiful separation of concerns that says widgets describe what you want, while RenderObjects do the actual work.

Think of it this way: widgets are like blueprints, and RenderObjects are the construction workers that build from those blueprints. Most of the time, Flutter handles this translation automatically. But when we need custom behavior 'like our selective overlay' we need to create this bridge ourselves.

class _SelectiveOverlay extends SingleChildRenderObjectWidget {
  final List<GlobalKey> widgetKeys;
  final HighlightStyle style;
  final VoidCallback? onDarkAreaTap;

SingleChildRenderObjectWidget is our bridge. It's a special type of widget that says: "I'm going to create my own custom RenderObject to handle the heavy lifting."

Our _SelectiveOverlay widget is quite simple. It holds three pieces of configuration:

widgetKeys: The list of GlobalKeys pointing to widgets we want to highlight
style: Our HighlightStyle object containing colors, padding, and border radius
onDarkAreaTap: An optional callback for when users tap the dark overlay area

The createRenderObject Method

@override
RenderObject createRenderObject(BuildContext context) {
  return _RenderSelectiveOverlay(
    widgetKeys: widgetKeys,
    style: style,
    onDarkAreaTap: onDarkAreaTap,
  );
}

This is where the magic starts. When Flutter builds our widget tree and encounters _SelectiveOverlay, it calls createRenderObject(). This method's job is simple: create the RenderObject that will do the actual painting and hit testing.

Think of this like a factory pattern. The widget is the factory, and it produces a worker (the RenderObject) that knows how to do the job. This separation is crucial because widgets are rebuilt frequently (they're cheap and immutable), but RenderObjects stick around and do the expensive work like layout, painting, and hit testing.

The updateRenderObject Method

Here's where things get interesting. Remember how I said widgets are rebuilt frequently? Well, we don't want to throw away and recreate our RenderObject every time, that would be wasteful. Instead, Flutter is smart! When our widget rebuilds with new data, it calls updateRenderObject() to pass the new configuration to the existing RenderObject.

@override
void updateRenderObject(
  BuildContext context,
  _RenderSelectiveOverlay renderObject,
) {
  renderObject
    ..widgetKeys = widgetKeys
    ..style = style
    ..onDarkAreaTap = onDarkAreaTap;
}

This is Flutter's optimization in action. We're essentially saying: "Hey, RenderObject, here's your updated configuration. If anything changed, you'll need to repaint."

Why This Architecture Matters

Now the real question is: "Why do we need all that? Couldn't we just use CustomPaint like usual?" Fair question! Well, we could use CustomPaint for the drawing part, but we'd still struggle with the hit testing. By going down to the RenderObject level, we get complete control over both painting and how taps are handled. This is the secret sauce that lets us create "holes" in our overlay that pass taps through to the buttons underneath.

This widget layer is lightweight and declarative, it just describes what we want. The real heavy lifting happens in the _RenderSelectiveOverlay class, which we're about to explore.

The Heart of the System: Understanding RenderBox

Now we're getting to the exciting part, the _RenderSelectiveOverlay RenderBox. This is where all the painting, the hit testing, and the performance optimizations happens, that make our overlay silky smooth. Don't worry if this looks intimidating at first. We'll break it down piece by piece, and by the end, you'll understand exactly how Flutter's rendering engine works under the hood.

Setting Up Our RenderBox

class _RenderSelectiveOverlay extends RenderBox {
  List<GlobalKey> _widgetKeys;
  HighlightStyle _style;
  VoidCallback? _onDarkAreaTap;

  _RenderSelectiveOverlay({
    required List<GlobalKey> widgetKeys,
    required HighlightStyle style,
    VoidCallback? onDarkAreaTap,
  }) : _widgetKeys = widgetKeys,
       _style = style,
       _onDarkAreaTap = onDarkAreaTap;

  List<GlobalKey> get widgetKeys => _widgetKeys;
  set widgetKeys(List<GlobalKey> value) {
    if (_widgetKeys == value) return;
    _widgetKeys = value;
    markNeedsPaint(); // Trigger the rebuild of the Overlay
  }

  HighlightStyle get style => _style;
  set style(HighlightStyle value) {
    if (_style == value) return;
    _style = value;
    markNeedsPaint(); // Trigger the rebuild of the Overlay
  }

  VoidCallback? get onDarkAreaTap => _onDarkAreaTap;
  set onDarkAreaTap(VoidCallback? value) {
    _onDarkAreaTap = value; // No need for visual rebuild
  }

Our RenderBox extends Flutter's RenderBox class, which is the base for all 2D rectangular rendering. We store three private fields that hold our configuration. But here's the thing, we need to be smart about how they're updated.

These getters and setters are doing something clever. When updateRenderObject() passes new values from the widget layer, these setters spring into action. First, they check: "Is this actually a new value?" If the value hasn't changed, we bail out early. There is no point in doing unnecessary work.

But if the value has changed, we update the field and then call markNeedsPaint(). This is our way of telling Flutter: "Hey, something visual changed! You need to repaint me on the next frame." Without this call, you could change the highlighted buttons or overlay color, and nothing would happen on screen. The data would update, but the pixels wouldn't!

Defining Our Size

@override
bool get sizedByParent => true;

@override
Size computeDryLayout(BoxConstraints constraints) {
  return constraints.biggest;
}

Here's a cool Flutter optimization. By returning true from sizedByParent, we're telling Flutter: "My size depends only on my constraints, not on my children or any other factors." This allows Flutter to skip some expensive layout calculations.

The computeDryLayout method then says: "Give me the biggest size you'll allow." Since we're using Positioned.fill in our widget tree, we want to cover the entire screen, so we take up all available space. The term "dry layout" means we're calculating size without any side effects, pure calculation.

The Paint Method: Creating Holes in the Darkness

Now for the main event, the painting logic. This is where we create that dark overlay with transparent holes for our highlighted widgets.

  @override
  void paint(PaintingContext context, Offset offset) {
    final canvas = context.canvas;
    final size = this.size;

    final paint = Paint()
      ..color = _style.overlayColor
      ..style = PaintingStyle.fill;

    final path = Path()..addRect(Rect.fromLTWH(0, 0, size.width, size.height));

First, we grab the canvas (our drawing surface) and set up our paint brush. The Paint object is like configuring a real paintbrush. We're saying "use this color" and "fill shapes completely" (not just stroke their outlines). Here's where it gets clever. We start by creating a Path and adding a rectangle that covers the entire screen. At this point, if we drew this path, we'd have a solid overlay blocking everything. But we're not done yet!

Looping through highlighted Widgets

for (final key in _widgetKeys) {
  final renderBox = key.currentContext?.findRenderObject() as RenderBox?;

  if (renderBox == null || !renderBox.attached) continue;

Now we loop through each GlobalKey pointing to a widget we want to highlight. For each key, we try to get its RenderObject. The null check (renderBox == null) handles cases where the widget hasn't been built yet, and the attached check prevents crashes if the widget is being removed from the tree. This is defensive programming at its best, we're handling edge cases that could occur during animations, page transitions, or rapid rebuilds.

final position = renderBox.localToGlobal(Offset.zero);
  final widgetSize = renderBox.size;

  final widgetRect = Rect.fromLTWH(
    position.dx - (_style.padding / 2),
    position.dy - (_style.padding / 2),
    widgetSize.width + _style.padding,
    widgetSize.height + _style.padding,
  );

  path.addRRect(
    RRect.fromRectAndRadius(
      widgetRect,
      Radius.circular(_style.borderRadius),
    ),
  );
}

For each widget we want to highlight, we need to know: "Where is it on the screen?" and "How big is it?" The localToGlobal(Offset.zero) call converts the widget's local top-left corner (0, 0) to global screen coordinates. Then we create a rectangle that's slightly larger than the widget itself. That's our padding creating a visual "breathing room" around the highlighted area. Finally, we add each highlighted area to our path as a rounded rectangle.

The final touch

path.fillType = PathFillType.evenOdd;
canvas.drawPath(path, paint);

This is the moment everything comes together! The PathFillType.evenOdd is the secret that creates our holes. Here's how it works: imagine drawing a line from outside the screen to any point. Count how many times that line crosses a shape boundary. If the count is odd, fill that area. If it's even, leave it empty.

So for our overlay:

Points outside everything: 1 crossing (the screen rectangle) = odd = filled ✓
Points inside a highlighted area: 2 crossings (screen + highlight) = even = empty ✓

It's like magic, but it's just clever math! This single line is what creates those transparent "holes" in our dark overlay.

Hit Testing: Making the Magic Interactive

The painting makes things look right, but we still need to make them behave right. When a user taps the screen, how do we decide what happens?

@override
bool hitTest(BoxHitTestResult result, {required Offset position}) {
  for (final key in _widgetKeys) {
    final renderBox = key.currentContext?.findRenderObject() as RenderBox?;

    if (renderBox == null || !renderBox.attached) continue;

    final widgetPosition = renderBox.localToGlobal(Offset.zero);
    final widgetSize = renderBox.size;

    final rect = Rect.fromLTWH(
      widgetPosition.dx - (_style.padding / 2),
      widgetPosition.dy - (_style.padding / 2),
      widgetSize.width + _style.padding,
      widgetSize.height + _style.padding,
    );

    if (rect.contains(position)) {
      return false;
    }
  }

Flutter's hit testing works from top to bottom in the widget tree. When our overlay's hitTest is called, we check: "Did the user tap inside any of our highlighted areas?" Notice we're using the same rectangle calculation as our paint method. This consistency is crucial. The visual holes and the interaction holes must match perfectly.
If the tap is inside a highlighted area, we return false. This is our way of saying: "Nope, I'm not handling this tap. Let it pass through to the widget underneath!" This is what makes the buttons still work even though there's an overlay on top of them.

if (size.contains(position)) {
    _onDarkAreaTap?.call();
    result.add(BoxHitTestEntry(this, position));
    return true;
  }

  return false;
}

But if the tap is in the dark overlay area (not in any highlighted region), we handle it ourselves. We call the callback (if one was provided), add ourselves to the hit test result, and return true to stop the hit test from continuing to widgets below.

The final return false is a safety net for taps that somehow fall outside our bounds—though in practice, this shouldn't happen since we fill the entire screen.

The Conclusion

And that’s pretty much it! We started with a simple UI and gradually built our way up from a basic Stack to a fully custom overlay powered by RenderBox and Paint. Along the way, we explored how Flutter moves from widgets to pixels, how to locate widgets on the screen using GlobalKeys, and how to draw directly on the canvas to create that spotlight effect.

More importantly, we took a look under the hood. We didn’t just use Flutter’s rendering system, we learned how it works. From layering widgets, to custom painting, to controlling hit testing, every piece of this solution shows how flexible Flutter can be when you need to go beyond standard widgets. To be honest, this kind of approach isn’t something you’ll need every day, but when you do (like onboarding flows, tutorials, coach marks, or any kind of custom visual effect ), understanding the rendering pipeline makes all the difference. Hopefully, this article gave you both a practical feature you can reuse and a deeper appreciation of how Flutter actually draws things on the screen.

If you enjoyed this article and want to stay connected, feel free to connect with me on LinkedIn.

If you'd like to dive deeper into the code and contribute to the project, visit the repository on GitHub.

Was this guide helpful? Consider buying me a coffee!☕️ Your contribution goes a long way in fuelling future content and projects. Buy Me a Coffee.

As always, feel free to experiment, tweak the code, and make it your own. Happy coding, Flutter friends!

The Ultimate Guide to Flutter Lists with Bloc : Part 3

Thanasis Traitsis — Sun, 11 May 2025 19:54:12 +0000

Part 3 : Powerful Filtering for Your Flutter Listings

Welcome back to our Flutter listing series! In Parts 1 and 2, we built a powerful Pokémon listing with pagination and infinite scrolling. Now it's time to introduce another essential feature of any good listing: filtering.

Effective filtering transforms a simple list into a powerful tool that helps users find exactly what they're looking for, without extra effort and with less time needed. Whether you're filtering Pokémon by type, searching products by category, or sorting messages by date, the principles remain the same.

In this third blog, we'll implement a complete filtering system for our Pokédex app. We'll create a simple FilterBloc that communicates seamlessly with our ListingBloc, apply filters efficiently without sacrificing performance, and ensure a smooth UX throughout the process.

Let's explore how to build a filtering system that's both powerful and maintainable, all while keeping our Pokémon list running smoothly.

Let's talk about the Filters

The filtering system of a listing is a complex feature. It needs to combine multiple filter criteria while ensuring the UI responds appropriately throughout the application. This complexity requires the filter to maintain its own state. And that's where our beloved friend Bloc comes to the rescue.

Creating the Filters State

First, we need to consider that we don't need multiple filter states. The PokemonFilterState is singular, and only its values change as users select different filtering options. We can start with a simple implementation:

final class PokemonFilterState extends Equatable {
  final Map<String, dynamic> selectedFilters;

  const PokemonFilterState({this.selectedFilters = const {}});

  PokemonFilterState copyWith({Map<String, dynamic>? selectedFilters}) {
    return PokemonFilterState(
      selectedFilters: selectedFilters ?? this.selectedFilters,
    );
  }

  @override
  List<Object> get props => [selectedFilters];
}

I chose Map<String, dynamic> for the selected filters because it gives us flexibility to store different types of filter values. For example, we might need to store string values for Pokemon types, numeric ranges for stats, or boolean values for availability filters—all within the same state object.

What makes this approach powerful is that I can track every filter change reliably by using consistent key values as identifiers. By centralizing these keys—either fetching them from an API or storing them as static constants—I ensure my UI and business logic remain perfectly aligned. This prevents filter-related bugs and makes the codebase more maintainable as the filtering system grows in complexity.

Apply filter changes with Events

Moving on, now that we initialized our state with an empty value, we need to figure out a way to add some values. That's where the events step up. But, what are the actual events that we need? Let's figure out first how to add a value. For this example, we will cover only two types of filters with the first one being the favorite pokemons, and the second one is based on the type of each pokemon. Let's make it!

Toggling the filters

sealed class PokemonFilterEvent extends Equatable {
  const PokemonFilterEvent();

  @override
  List<Object> get props => [];
}

class ToggleFilter extends PokemonFilterEvent {
  final bool? showFavorites;
  final Set<String>? types;

  const ToggleFilter({this.showFavorites, this.types});
}

With this approach, we separate the logic of each filter by providing its own dedicated variable. This gives us clearer code and more flexibility when handling different filter types:

For favorite Pokémon, we simply need a boolean flag (showFavorites) - either we want to see favorites only (true) or we don't (false). Nothing more complex is required here.
For Pokémon types, we use a Set<String> instead of a List. Why? Because each type should only appear once in our filter criteria (there's no scenario where we'd need to apply "Water" type twice). Sets inherently prevent duplicates and offer performance benefits when checking if a value exists.

💡Always use the right tools for the job. Sets aren't just about preventing duplicates - they also provide powerful operations like union (combining filters), intersection (finding common elements), and difference (removing specific filters) that make complex filter manipulations much cleaner. When your app grows and users demand more sophisticated filtering capabilities, you'll thank yourself for this decision.💡

Now, our event is ready to receive filter changes. Notice how we made both parameters nullable? This allows us to toggle just one filter at a time without affecting the others. For instance, a user might want to change only the type filter without modifying their favorites preference.

Remove the filters

Adding filters is only half the job. Users also need an easy way to remove them. Thanks to the well-structured foundation we’ve built, implementing filter removal is pretty straightforward.

To remove a specific filter value, we simply need two pieces of information:

The key of the filter (e.g. "type")
The value we want to remove (e.g. "Fire")

This is important because some filters, like Pokémon types, can support multiple values at once. Here's how we model these events:

class RemoveFilter extends PokemonFilterEvent {
  final String filterKey;
  final String valueToRemove;

  const RemoveFilter({required this.filterKey, required this.valueToRemove});
}

class RemoveAllFilters extends PokemonFilterEvent {}

With this structure, removing a single filter or clearing all filters becomes a clean, manageable task, one that fits perfectly into our event-driven system.

Combine everything into Bloc

Now comes the fun part! We've built a clean event structure and designed a state to hold our filter data. It's time to glue everything together into a working Bloc.

Bloc Constructor

To begin, let's initialize our Bloc with a proper constructor. We'll register each event type with its corresponding handler method, creating a clear mapping between user actions and our business logic:

  PokemonFilterBloc() : super(const PokemonFilterState()) {
    on<ToggleFilter>(_onToggleFilter);
    on<RemoveFilter>(_onRemoveFilter);
    on<RemoveAllFilters>(_onRemoveAllFilters);
  }

This constructor initializes our Bloc with an empty PokemonFilterState and registers three event handlers that we'll implement next.

Toggle filter

void _onToggleFilter(ToggleFilter event, Emitter<PokemonFilterState> emit) {
  final updatedFilters = Map<String, dynamic>.from(state.selectedFilters);

  if (event.showFavorites != null) {
    final currentValue =
        state.selectedFilters[AppStrings.filterStateFavoriteKey];

    if (currentValue == true) {
      updatedFilters.remove(AppStrings.filterStateFavoriteKey);
    } else {
      updatedFilters[AppStrings.filterStateFavoriteKey] = true;
    }
  }

  if (event.types != null) {
    updatedFilters[AppStrings.filterStateTypesKey] = event.types;
  }

  emit(state.copyWith(selectedFilters: updatedFilters));
}

This implementation does several important things:

It creates a mutable copy of our current filters map to work with
For favorites, it toggles the value - removing it if already true, or setting it to true if not present
For Pokémon types, it simply updates the map with the new set of types
Finally, it emits a new state with the updated filters

Notice how we're using string constants from AppStrings as keys. This centralization ensures consistency between our Bloc implementation and UI code, making maintenance much easier.

Removing filters (1-by-1 or all of them)

Of course, we need to give users the ability to remove filters they've applied. Our implementation handles two scenarios: removing individual filter values and clearing all filters at once.

Don't miss out on the comments inside the code. It will give you a clear view on how everything works.

void _onRemoveFilter(RemoveFilter event, Emitter<PokemonFilterState> emit) {
  final updatedFilters = Map<String, dynamic>.from(state.selectedFilters);

  if (updatedFilters[event.filterKey] is bool) {
    // For boolean filters (like favorites), simply remove the entire key
    updatedFilters.remove(event.filterKey);
  } else if (updatedFilters[event.filterKey] is Set<String>) {
    // For set-based filters (like types), remove just the specific value
    final originalSet = updatedFilters[event.filterKey];
    final updatedSet = Set<String>.from(originalSet)
      ..remove(event.valueToRemove);

    // If removing this value leaves the set empty, remove the entire filter key
    if (updatedSet.isEmpty) {
      updatedFilters.remove(event.filterKey);
    } else {
      updatedFilters[event.filterKey] = updatedSet;
    }
  }

  emit(state.copyWith(selectedFilters: updatedFilters));
}

void _onRemoveAllFilters(
    RemoveAllFilters event, Emitter<PokemonFilterState> emit) {
  emit(state.copyWith(selectedFilters: {}));
}

This implementation demonstrates the flexibility of our Map<String, dynamic> approach. The _onRemoveFilter method handles different filter types:

Boolean filters (such as favorites) are handled with a simple key removal, just toggle it off and it's gone
For collection-based filters like Pokémon types, we surgically remove just the selected value while preserving others
We maintain clean state by automatically removing empty collections. There is no need to track filters that don't filter anything

The companion _onRemoveAllFilters method offers a "reset button" functionality by replacing the entire filters map with an empty one, effectively returning to a fresh start.

Communication between Blocs

Now that we have our Filters bloc ready to go, we need to make something out of it. In order to see the filters work, we need to apply them to our current Pokémon list. But wait, our list is in our Pokémon List Bloc, so how do we combine these two Blocs?

A simple solution that comes to mind right away is utilizing BlocListener and handling everything in our UI. But let's be honest, do we really want to complicate our UI with this business logic? I don't think so. So, let me show you a more elegant approach!

final PokemonFilterBloc filterBloc;
late final StreamSubscription filterSubscription;

final Map<String, PokemonEntity> pokemonMap = {};
Map<String, PokemonEntity> filteredMap = {};

bool showOnlyFavorites = false;
Set<String> selectedTypes = {};
bool isFiltering = false;

  PokemonListBloc(this.filterBloc) : super(PokemonListInitial()) {

    filterSubscription = filterBloc.stream.listen((filterState) {
      showOnlyFavorites =
          filterState.selectedFilters[AppStrings.filterStateFavoriteKey] ??
              false;
      selectedTypes =
          filterState.selectedFilters[AppStrings.filterStateTypesKey] ?? {};

      if (showOnlyFavorites || selectedTypes.isNotEmpty) {
        isFiltering = true;
        if (filteredMap.isEmpty) {
          filteredMap = Map.from(pokemonMap);
        }
      } else {
        isFiltering = false;
      }

      add(ApplyFilters());
    });

    on<InitialFetch>(_onInitialPokemonFetch);
    on<FetchNextPage>(_onFetchNextPage);
    on<ToggleFavoriteStatus>(_onToggleFavoriteStatus);
    on<ApplyFilters>(_onApplyFilters);
  }

What's happening here? Instead of having our UI act as the intermediary between blocs (bad practise), we're directly injecting our filterBloc into our PokemonListBloc. This creates a clean dependency that follows the natural flow of our application logic: filters affect the list, not the other way around.

The real magic happens with filterSubscription. We're creating a stream subscription that listens to any changes in the filter state. Basically, the stream is a spy that works for our List Bloc. His secret mission is to hear everything that happens in the Filter Bloc headquarters and immediately report back. Whenever our spy detects a change in filter operations, it secretly dispatches an ApplyFilters event to its commander (the List Bloc), all without the UI ever knowing about this covert operation. How we actually act on it:

Extract the current filter values (favorites and types)
Search if any filtering is currently active
Prepare our data structure for filtered results if needed
Dispatch an internal ApplyFilters event to the list bloc itself

This approach keeps our UI clean and simple while maintaining proper separation of concerns. The List Bloc is responsible for maintaining and filtering the list, and it simply consumes the filter criteria from the filter bloc.

⚠️ Don’t forget to close your ears when you’re done listening!
Since we subscribed to another bloc’s stream, it’s critical to cancel that subscription in close(). Otherwise, it leads to memory leaks. Always clean up after your listeners to keep your app healthy and efficient!

  @override
  Future<void> close() {
    filterSubscription.cancel();
    return super.close();
  }

Okay now that we took care of everything, let's take a closer look on the List Bloc and how it actually handles the filters.

New List Bloc with Two Lists

Now that our filter data is flowing smoothly between blocs, we need to address one final architectural challenge: managing our filtered and unfiltered data efficiently.

To maintain proper separation of concerns, our listing implementation uses two variables:

pokemonMap: Our source of truth that contains the complete, unfiltered collection of Pokémon
filteredMap: A derived view that contains only the Pokémon matching our current filter criteria

This dual-map approach gives us significant performance advantages. We can apply complex filtering operations without repeatedly processing the entire dataset, and we maintain quick access to our original data when filters are cleared.

Apply Filters Event

There is one main event that handles filter changes — the ApplyFilters event. Remember inside our StreamSubscription when we secretly called:

add(ApplyFilters());

Here is what's going on inside this event:

  void _onApplyFilters(
      ApplyFilters event, Emitter<PokemonListState> emit) async {
    emit(PokemonListLoading());

    try {
      if (showOnlyFavorites) {
        await _loadUnloadedFavoritePokemons();
      } else if (selectedTypes.isNotEmpty) {
        await _loadPokemonsBySelectedTypes();
      }

      _emitSuccessState(
        emit,
        currentMap: isFiltering ? filteredMap : pokemonMap,
      );
    } catch (e) {
      emit(
          PokemonListError(message: "${AppStrings.failedToLoad}: ${e.toString()}"));
    }
  }

  // This is what's going on inside the emit success state:
    void _emitSuccessState(Emitter<PokemonListState> emit,
      {Map<String, PokemonEntity>? currentMap}) {
    emit(PokemonListSuccess(
      pokemonMap: currentMap ?? pokemonMap,
      pagination: pagination,
      favoritePokemons: favoriteIds.length,
      showOnlyFavorites: showOnlyFavorites,
      selectedTypes: selectedTypes,
    ));
  }

What makes this special is that we don’t rebuild or mutate the original pokemonMap. Instead, if filters are active, we work with a separate filteredMap, leaving the full dataset intact.

And here’s the big twist: even inside the event, we don’t slice and filter data manually. We simply check if the data we need already exists. If not? We fetch only what’s missing.

No waste. No duplication. No rebuild.

But where is the real filtering logic? Thought you'd never ask! It’s all deferred to the PokemonListSuccess state. That’s where we dynamically compute what to show, based on the user's filters and our clean maps.

Ready for the big reveal? I present you... THE NEW STATE:

final class PokemonListSuccess extends PokemonListState {
  final Map<String, PokemonEntity> pokemonMap;
  final int pagination;
  final int favoritePokemons;
  final bool showOnlyFavorites;
  final Set<String> selectedTypes;

  const PokemonListSuccess({
    required this.pokemonMap,
    this.pagination = 0,
    this.favoritePokemons = 0,
    this.showOnlyFavorites = false,
    this.selectedTypes = const {},
  });

  List<PokemonEntity> getPokemons() {
    return PokemonDisplayHelper.getDisplayedPokemons(
      pokemon: pokemonMap,
      showOnlyFavorites: showOnlyFavorites,
      selectedTypes: selectedTypes,
    );
  }

  @override
  List<Object> get props => [
        pokemonMap,
        pagination,
        favoritePokemons,
        showOnlyFavorites,
        selectedTypes
      ];
}

Instead of keeping filtered results in the state itself, we are making the state compute them on demand through the getPokemons() method. Why? Because this approach has several powerful advantages. For example, our widgets (UI) only need to call getPokemons() without knowing about the filtering complexity behind the scenes. Plus, the state is pretty clean because we exclude the complex part into a helper.

Enter the Helper

The real workhorse behind our filtering system is the PokemonDisplayHelper class:

class PokemonDisplayHelper {
  static List<PokemonEntity> getDisplayedPokemons({
    required Map<String, PokemonEntity> pokemon,
    required bool showOnlyFavorites,
    required Set<String> selectedTypes,
    SortOption sortBy = SortOption.id,
  }) {
    List<PokemonEntity> filtered = pokemon.values.where((pokemon) {
      final matchesFavorite = !showOnlyFavorites || pokemon.isFavorite;
      final matchesType = selectedTypes.isEmpty ||
          pokemon.types.any((type) => selectedTypes.contains(type.name));

      return matchesFavorite && matchesType;
    }).toList();

    _sortPokemon(filtered, sortBy);

    return filtered;
  }

  static void _sortPokemon(List<PokemonEntity> list, SortOption sortBy) {
    switch (sortBy) {
      case SortOption.id:
        list.sort((pokemonA, pokemonB) =>
            int.parse(pokemonA.id).compareTo(int.parse(pokemonB.id)));
        break;
      case SortOption.name:
        list.sort(
            (pokemonA, pokemonB) => pokemonA.name.compareTo(pokemonB.name));
        break;
      case SortOption.type:
        list.sort((pokemonA, pokemonB) =>
            pokemonA.types.first.name.compareTo(pokemonB.types.first.name));
        break;
    }
  }
}

Let's break down what's happening in our filtering method:

We start with values from our Map<String, PokemonEntity> since we need to work with the actual objects
We filter using Dart's where() method, applying our filtering rules:
- A Pokémon passes the favorite filter if either showOnlyFavorites is false OR the Pokémon is marked as favorite
- A Pokémon passes the type filter if either no types are selected OR it has at least one matching type
We combine these conditions with a logical AND (&&), so a Pokémon must satisfy both filters to be included
Finally, we apply sorting to the filtered list based on the requested sort option

The UI: Stupidly Simple

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

  @override
  Widget build(BuildContext context) {
    return BlocBuilder<PokemonListBloc, PokemonListState>(
      builder: (context, state) {
        switch (state) {
          case PokemonListSuccess success:
            return PokemonListingSuccess(pokemons: success.getPokemons());
          case PokemonListError error:
            return Center(
              child: Text(error.message),
            );
          default:
            return PokemonListingLoading();
        }
      },
    );
  }
}

That's it. No, seriously, that's the entire listing component! Just a simple BlocBuilder that renders different widgets based on the state.

Conclusion

There is no need to dive deeper into the UI implementation. You now have all the business logic ready and you can use it however you want in your own projects. You're free to go and make the best out of these solid fundamentals we've created for filtering. If you want to see my complete approach including the UI components and styles, you can always check out the GitHub repository linked at the bottom of this blog.

If you enjoyed this article and want to stay connected, feel free to connect with me on LinkedIn.

If you'd like to dive deeper into the code and contribute to the project, visit the repository on GitHub.

Was this guide helpful? Consider buying me a coffee!☕️ Your contribution goes a long way in fuelling future content and projects. Buy Me a Coffee.

The Ultimate Guide to Flutter Lists with Bloc : Part 2

Thanasis Traitsis — Sun, 30 Mar 2025 20:04:57 +0000

Part 2 : Pagination & Infinite Scrolling

Welcome back, Flutter devs! In Part 1, we explored how to build clean and efficient listings using Flutter and Bloc, powered by the PokéAPI. We successfully fetched data, displayed Pokémon cards, handled state with precision, and optimized our UI for performance.

Now, in Part 2, we’re stepping it up.

We’re going to implement infinite scrolling and smart pagination. Think about the experience you get on top-tier apps. You know what I am talking about. The list just keeps going, with zero loading interruptions, and new content appears right as you need it. Well, that’s what we’re building.

We’ll cover:

How to detect when to load more items
How to fetch additional data behind the scenes
How to prevent janky rebuilds or duplicate fetches
And how to structure this cleanly inside Bloc

By the end, your Pokémon listing will feel instant, scalable, and app-store ready. Let’s dive in.

What’s the Problem with Basic Pagination?

The classic approach to pagination usually goes something like this:

Wait until the user scrolls to the bottom
Show a loading spinner
Fetch the next batch of items
Append them to the list
Repeat

And technically… that works. But it’s not the kind of experience users expect anymore. Think about the apps you use every day. Instagram, TikTok, Ebay... You never see a loader. You never wait. You just scroll, and things appear as if they were already there.

That’s because these apps don't just paginate, they anticipate. And this is exactly what we are going to do as well.

What We’re Building

In this part, we’re going to build a prefetching system. That means:

You’ll load more items before the user hits the bottom
You’ll fetch multiple pages ahead in the background
You’ll make the scroll feel continuous and uninterrupted
And most importantly, you’ll do it all cleanly with Bloc and efficient memory usage

This approach gives you the best of both worlds: great UX and great performance at the same time. Let's go!

Pagination the right way

To implement pagination, we need a new Bloc event. Unlike the initial fetch, this event is triggered when we want to load more data, either while scrolling or during background prefetching.

class FetchNextPage extends PokemonListEvent {}

How to track the progress of the list

Here's the thing:

When you add new items to your list and emit a state, Bloc (via Equatable) uses props to determine if the state has changed. If your list grows but the object reference stays the same, Bloc assumes nothing changed, and doesn’t rebuild the UI. So, many developers solve this by doing something like this:

emit(PokemonListSuccess(pokemons: List.of(pokemonList)));

Why this works? Because in our Bloc, we have set our props to look on the pokemons value. So, by implementing the List.of we create a new instance of the list. The Bloc sees a new instance, and as a result we get a new state with the updated list.

Does this work? Yes. Do we like it? Of course not. Let me explain you the reason.

With this approach, you're copying the entire list every time, even when just a few items are added. If you’ve got 1,000+ Pokémon already loaded, that’s an expensive operation for no real reason.

The Better Way: Emit a Version Counter

Instead of copying the list, we introduce a simple int pagination value that only increases when the list changes:

final class PokemonListSuccess extends PokemonListState {
  final List<PokemonEntity> pokemons;
  final int pagination;

  const PokemonListSuccess({
    required this.pokemons,
    required this.pagination,
  });

  @override
  List<Object> get props => [pagination]; 
}

Now, whenever we fetch more data or toggle a favorite:

pagination++;
emit(PokemonListSuccess(pokemons: pokemonList, pagination: pagination));

By increasing the pagination, we trigger the emit every time we make a change in our list.
What this gives us:

No need to copy lists (which saves memory and processing time)
Bloc still detects a state change because pagination changes
UI rebuilds as expected, even though the list reference stays the same

Update Bloc and Events

Because the logic of the initial fetch is exactly the same with every fetch we will execute in any page, we will separate the fetch pokemon logic outside of the events. Good old DRY logic.

  Future<void> _fetchPokemons(Emitter<PokemonListState> emit,
      {int? chosenLimit}) async {
    try {
      final List<String> pokemonUrls = await PokemonRepositories()
          .fetchPokemonUrls(limit: chosenLimit ?? limit, offset: offset);

      if (pokemonUrls.isNotEmpty) {
        final List<PokemonEntity?> fetchedPokemons = await Future.wait(
            pokemonUrls
                .map((url) => PokemonRepositories().fetchPokemonDetails(url)));

        pokemonList.addAll(fetchedPokemons.whereType<PokemonEntity>());

        pagination++;
        offset += chosenLimit ?? limit;

        emit(PokemonListSuccess(pokemons: pokemonList, pagination: pagination));
      } else {
        emit(PokemonListError(message: "There are no more pokemons"));
      }
    } catch (e) {
      emit(PokemonListError(
          message: "Failed to fetch Pokémon: ${e.toString()}"));
    }
  }

Now, all you have to do, is call this function from the events we created, and keep track of the key variables:

pagination (for triggering new state changes)
offset (set the starting point of the next fetch, from the end of the last one)

...
  final List<PokemonEntity> pokemonList = [];
  int pagination = 0;
  int offset = 0;
  final int limit = 30;

  PokemonListBloc() : super(PokemonListInitial()) {
    on<InitialFetch>(_onInitialPokemonFetch);
    on<FetchNextPage>(_onFetchNextPage);
    on<ToggleFavoriteStatus>(_onToggleFavoriteStatus);
  }

  void _onInitialPokemonFetch(
      InitialFetch event, Emitter<PokemonListState> emit) async {
    emit(PokemonListLoading());
    await _fetchPokemons(emit, chosenLimit: event.firstPokemon);
  }

  void _onFetchNextPage(
      FetchNextPage event, Emitter<PokemonListState> emit) async {
    await _fetchPokemons(emit);
  }
  ...

Pagination with an int

Here’s the magic line:

pagination++;

Instead of copying and re-emitting the whole list (which could already have hundreds of items), we simply bump a counter.

This triggers a new Bloc state, and thanks to:

@override
List<Object> get props => [pagination];

…the UI rebuilds as expected. Enough with the Bloc, I think it's time to take a look in the UI.

UI implementation

Now that our Bloc handles everything, it’s time to connect the logic to the UI and turn this into a scrollable, preloading Pokédex that feels instant and endless. Let's break down the logic in small parts.

Part 1: When should I fetch extra Pokémon?

When using ListView.builder, we gain access to something really useful: the index of each item as it’s being built. As we mentioned in Part 1, ListView.builder is highly memory-efficient, it doesn’t build the entire list at once, just what's visible on screen plus a few more. This gives us the perfect opportunity to detect when the user is getting close to the end of the list and dispatch an event to fetch more Pokémon. Here's a basic example:

...
child: ListView.builder(
        cacheExtent: 350,
        itemCount: widget.pokemons.length,
        itemBuilder: (context, index) {
          if (index >= 30) {
              context.read<PokemonListBloc>().add(FetchNextPage());
          }
...

Keep in mind, we initially fetch 50 Pokémon, that's why we start fetching the next page on Pokémon #30

Now, when the user reaches at the pokemon #30, the FetchNextPage() will execute, and we will add 30 more Pokémon to the list. Amazing right? Something is missing though...

Part 2: Avoid fetching the same page twice

The logic above works, but there’s one problem. If the ListView.builder keeps building items beyond index 30 (and it will), the condition if (index >= 30) will be true forever. That means we’ll keep dispatching the FetchNextPage event over and over, even if we already fetched it.

To solve this, we need to add a simple guard. A local boolean flag that prevents multiple fetches at once. Something like this:

bool isFetchingMore = false;

...

if (index >= widget.pokemons.length - 30 && !isFetchingMore) {
  isFetchingMore = true;
  context.read<PokemonListBloc>().add(FetchNextPage());
}

Then, once the new data comes in, we reset the flag to false using a BlocListener:

BlocListener<PokemonListBloc, PokemonListState>(
  listener: (context, state) {
    if (state is PokemonListSuccess) {
      isFetchingMore = false;
    }
  },
  child: ListView.builder(...)
)

Okat now let's take a step back and see what we have accomplished:

We fetch new Pokémon before the user reaches the bottom of the list
We prevent duplicate fetches by tracking the loading state

And now, to complete the perfect infinite scroll experience, we’re going to add one final enhancement. Prefetching a few pages in advance during the initial load.

Part 3: Prefetch and Infinite Scrolling

The idea is simple: instead of fetching just one batch of Pokémon when the app starts, we fetch multiple pages ahead in the background. This way, we’re always staying 2–3 pages ahead of the user, so they never catch up to the data or hit a visible loading state.

It looks like this in the Bloc:

void _onInitialPokemonFetch(
  InitialFetch event,
  Emitter<PokemonListState> emit,
) async {
  emit(PokemonListLoading());

  await _fetchPokemons(emit, chosenLimit: event.firstPokemon); // First page
  await _fetchPokemons(emit); // Page 2
  await _fetchPokemons(emit); // Page 3
  await _fetchPokemons(emit); // Page 4
}

These additional fetches happen immediately after the first one, giving the user a smooth experience from the very first scroll gesture.

Now, when the user reaches index 200, the app already has Pokémon 201–300 ready to go. No delays. No spinners. Just scroll and enjoy.

Finally, apply these small adjustments to the UI, because we want to stay ahead of the user like we already said:

if (index >= widget.pokemons.length - 100 &&
              widget.pokemons.length > 100) {
            if (!isFetchingMore) {
              isFetchingMore = true;
              context.read<PokemonListBloc>().add(FetchNextPage());
            }
          }

The final screen should look like this:

class PokemonListingSuccess extends StatefulWidget {
  final List<PokemonEntity> pokemons;

  const PokemonListingSuccess({
    super.key,
    required this.pokemons,
  });

  @override
  State<PokemonListingSuccess> createState() => _PokemonListingSuccessState();
}

class _PokemonListingSuccessState extends State<PokemonListingSuccess> {
  bool isFetchingMore = false;

  @override
  Widget build(BuildContext context) {
    return BlocListener<PokemonListBloc, PokemonListState>(
      listener: (context, state) {
        if (state is PokemonListSuccess) {
          isFetchingMore = false;
        }
      },
      child: ListView.builder(
        cacheExtent: 350,
        itemCount: widget.pokemons.length,
        itemBuilder: (context, index) {
          if (index >= widget.pokemons.length - 100 &&
              widget.pokemons.length > 100) {
            if (!isFetchingMore) {
              isFetchingMore = true;
              context.read<PokemonListBloc>().add(FetchNextPage());
            }
          }
          return Container(
            margin: EdgeInsets.only(top: index != 0 ? AppSpacing.md : 0),
            child: PokemonCard(
              key: ValueKey(widget.pokemons[index].id),
              pokemon: widget.pokemons[index],
            ),
          );
        },
      ),
    );
  }
}

Conclusion

That's it everybody! We have successfully delivered the best scrolling experience using Flutter + Bloc, completely from scratch. Not only did we manage to trigger pagination based on the list index, but we also prefetched multiple pages upfront to provide a truly seamless user experience.

This isn’t just a pagination strategy, it’s the foundation of how modern apps deliver seamless, high-performance data loading at scale.

Whether you're listing products, social feeds, restaurants, or Pokémon, this is a blueprint you can reuse again and again.

If you enjoyed this article and want to stay connected, feel free to connect with me on LinkedIn.

If you'd like to dive deeper into the code and contribute to the project, visit the repository on GitHub.

Was this guide helpful? Consider buying me a coffee!☕️ Your contribution goes a long way in fuelling future content and projects. Buy Me a Coffee.

The Ultimate Guide to Flutter Lists with Bloc : Part 1

Thanasis Traitsis — Sun, 23 Mar 2025 15:18:02 +0000

Part 1 : Introduction to Listings

Hello Flutter people! I’m back with a brand-new Flutter blog series, and this one is going to be special. We’re diving into a topic you’ll find in just about every real-world app: listings. Whether you’re displaying products, contacts, messages, or in our case, Pokémon (a.k.a. the greatest thing in the world), building smooth, scalable lists is a core skill for any Flutter developer.

In this first part of the series, we’ll focus on how to fetch and display data using Flutter + Bloc, and build a list that updates in real time, handles state efficiently, and delivers a great user experience. We’ll dive into ListView.builder, state management patterns, performance optimizations, and even sprinkle in some UI polish, all using the PokéAPI as our data source.

Ready to catch ’em all? Or should I say... display them all? Eh, forget about it, let’s get started with our Pokédex. 😅

What are we building?

Before we dive into the code, let’s take a moment to understand what we’re building and how it all comes together.

We’ll be using the open-source PokéAPI to fetch and display a list of Pokémon. Each card will include the Pokémon’s name, image, number, and types. As a little bonus, we’ll also make each card interactive by adding a favorite icon that users can toggle on or off, and all of this will be handled using Bloc for state management.

Now, don’t worry too much about the UI or styling. This blog will focus on data flow, and state handling. I’ll provide a link to the full GitHub repo at the end of the post with all the code, so you can dig in when you're ready.

How Does the PokéAPI Work?

The PokéAPI gives us everything we need, but not in a single request. Instead, we’ll use two API calls:

The first call gives us a list of Pokémon URLs, just enough to know which ones are available.
The second call fetches the details of each Pokémon individually using those URLs (name, ID, types, image, and more).

It might sound like extra work, but trust me, this gives us the flexibility to load detailed data only when we need it. It’s a great example of working with a two-step API flow, which you’ll run into often when working with public APIs or pagination.

How do we handle those API calls?

Like I mentioned earlier, we will use Bloc to handle our listing state. The states we will need are:

PokemonListInitial → the default state before anything happens
PokemonListLoading → shown while data is being fetched
PokemonListSuccess → returns the full list of Pokémon
PokemonListError → triggered when something goes wrong (e.g. no data, API failed)

As simple as it gets right? It gets even simpler when it comes to events. We only need a single event to kick off the initial fetch when the app launches:

class InitialFetch extends PokemonListEvent {
  final int firstPokemon;

  const InitialFetch(this.firstPokemon);
}

The int represents how many Pokémon we want to fetch on the first load. This lets us tell the Bloc:

“Hey, fetch the first n Pokémon starting from this index.”

Perfect setup for pagination later on 👀 🫢 (spoiler for Part 2?)

Let’s look at the event handler that handles this logic:

  void _onInitialPokemonFetch(
      InitialFetch event, Emitter<PokemonListState> emit) async {
    emit(PokemonListLoading());

    try {
      final List<String> pokemonUrls =
          await PokemonRepositories().fetchPokemonUrls(event.firstPokemon);

      if (pokemonUrls.isNotEmpty) {
        final List<PokemonEntity?> fetchedPokemons = await Future.wait(
            pokemonUrls
                .map((url) => PokemonRepositories().fetchPokemonDetails(url)));

        pokemonList.addAll(fetchedPokemons.whereType<PokemonEntity>());

        emit(PokemonListSuccess(pokemons: pokemonList));
      } else {
        emit(PokemonListError(message: "There are no more pokemons"));
      }
    } catch (e) {
      emit(PokemonListError(
          message: "Failed to fetch Pokémon: ${e.toString()}"));
    }
  }

Here’s what’s happening, step-by-step:

We emit the loading state to let the UI know something is happening in the background.
We fetch all the Pokémon URLs based on the number provided inside the PokemonRepositories.
We fetch the full details for each of those URLs (in parallel) using Future.wait.
We filter out any nulls (just in case) and add the valid Pokémon to our list.
We emit the PokemonListSuccess state with the final list.

By the way, this is how this Pokémon model looks like:

class PokemonEntity {
  final String id;
  final String name;
  final List<PokemonType> types;
  final String image;
  final bool isFavorite;

  const PokemonEntity({
    required this.id,
    required this.name,
    required this.types,
    required this.image,
    required this.isFavorite,
  });

  PokemonEntity copyWith({bool? isFavorite}) {
    return PokemonEntity(
      id: id,
      name: name,
      types: types,
      image: image,
      isFavorite: isFavorite ?? this.isFavorite,
    );
  }
}

How Do We Display the Pokémon in UI?

Once we have the data ready, it’s time to put it on the screen. And for this, we’ll use one of Flutter’s most powerful and efficient widgets: ListView.builder. But why this one?

Because unlike a regular Column or ListView(children: [...]), ListView.builder doesn’t build everything at once. It only builds the widgets that are currently visible on screen, and recycles them as you scroll.

This makes it perfect for long or infinite lists. Here is a quick breakdown of how everything works:

...
if (state is PokemonListSuccess) {
    return ListView.builder(
        itemCount: state.pokemons.length,
        itemBuilder: (context, index) {
            return Container(
                margin: EdgeInsets.only(top: index != 0 ? AppSpacing.md : 0),
                child: PokemonCard(
                  pokemon: state.pokemons[index],
                ),
              );
            },
          );
        }
...

itemCount tells Flutter how many items it should expect
itemBuilder gets called only when a new widget is needed

Flutter recycles previously built widgets as you scroll, this is why ListView.builder is so memory-efficient. This is pretty awesome if you ask me. But can we make it even more awesome?? Well, in Flutter everything is possible.

What if I told you... we could control how many pixels ahead Flutter preloads your list items?

Enter the cacheExtent ...

The cacheExtent controls the number of pixels outside the visible area that Flutter will preload list items. You can think of it like a "scroll buffer." If the screen height is 800 pixels and your cacheExtent is set to 300, Flutter will start building list items 300 pixels before they become visible.

By default, cacheExtent is set to 250 pixels, which works fine in many cases. But depending on your UI, this number might need some tuning. This is a powerful tool, but it comes with responsibility. It’s important to adjust it based on your specific scenario:

If your list items are small, lightweight, or don’t use heavy assets like images, the default value might be perfect.
If your list items are larger, or you're using images, shimmer loaders, or animated widgets, you may want to increase the cacheExtent to something like 300–600 pixels for a smoother UX.

⚠️ Tip: Going too high on cacheExtent may lead to increased memory usage, especially with complex lists. Try to keep it below 600 unless you’ve benchmarked for your specific case.

Extra Pro Tip: Add Keys to Your List Items

Why use a key? Because it gives Flutter a reliable way to track which widget is which, especially when your list updates dynamically. Without keys, Flutter identifies widgets by their position in the list (index). But once your list starts changing (like adding, deleting, or reordering items) relying on the index becomes dangerous.

Common issue: You delete the 3rd item in your data, expecting it to be the Pokémon with ID 0003.
But Flutter sees "item at index 2" and reuses the wrong widget, maybe deleting or updating the wrong card.

It might sound like a small difference, but it's a bug with a big UX impact.

The solution? Use a Unique Key Per Item

Now Flutter knows exactly which widget maps to which Pokémon, even if the order changes, or the list is updated.

The final List should look like this:

if (state is PokemonListSuccess) {
          return ListView.builder(
            cacheExtent: 350,
            itemCount: state.pokemons.length,
            itemBuilder: (context, index) {
              return Container(
                margin: EdgeInsets.only(top: index != 0 ? AppSpacing.md : 0),
                child: PokemonCard(
                  key: ValueKey(state.pokemons[index].id),
                  pokemon: state.pokemons[index],
                ),
              );
            },
          );
        }

Now that our Pokémon list is up and running, let’s make it feel more alive.

Toggling Favorites Pokémon

We’re going to add the ability to toggle a favorite icon on each Pokémon card, and we’ll do it the right way. Using Bloc, immutability, and the power of Equatable.

This isn’t just about clicking a heart icon.
It’s about learning how to update a single item in a list, emit the right Bloc state, and rebuild only what’s necessary.

First of all, we start by defining a new event in our Bloc. This event simply carries the pokemonId of the card we want to toggle.

class ToggleFavoriteStatus extends PokemonListEvent {
  final String pokemonId;

  const ToggleFavoriteStatus(this.pokemonId);

  @override
  List<Object> get props => [pokemonId];
}

Then, we add this event inside our PokemonListBloc.

  void _onToggleFavoriteStatus(
      ToggleFavoriteStatus event, Emitter<PokemonListState> emit) {
    if (state is PokemonListSuccess) {
      final currentState = state as PokemonListSuccess;

      final updatedList = currentState.pokemons.map((pokemon) {
        if (pokemon.id == event.pokemonId) {
          return pokemon.copyWith(isFavorite: !pokemon.isFavorite);
        }
        return pokemon;
      }).toList();

      emit(PokemonListSuccess(pokemons: updatedList));
    }
  }

Now, even though we’re emitting the same state class, you might be wondering:

“Why does this actually work? Shouldn’t Bloc ignore it since we didn’t change the state type?”

Great question, and this is where Equatable and immutability come into play.

When we emit the new PokemonListSuccess state, we’re passing in a brand-new list instance with a modified Pokémon object inside it. Since our Bloc state class overrides props like this:

@override
List<Object> get props => [pokemons];

Bloc uses Equatable to compare the new list against the previous one. And because it’s a different list object (new reference), Bloc considers it a new state, and triggers the rebuild.

Flutter then efficiently rebuilds only the widgets that need updating, thanks to:

The ListView.builder reusing widgets
Our use of ValueKey(pokemon.id) to help Flutter track which widgets changed

This is the power of immutability and Equatable working together. You change only what’s necessary, and Flutter takes care of the rest.

So yes, we’re using the same state type (PokemonListSuccess) again, but with new data inside, and that’s exactly what Bloc is built for.

Wrapping up Part 1

And there you have it! We’ve built a clean, efficient, and scalable listing system using Bloc, Equatable, and Flutter’s powerful rendering engine.

From setting up the API flow with the PokéAPI, to handling list state with Bloc, and finally making the list interactive with favorite toggles, we’ve covered the essential concepts that power most real-world listing features in mobile apps.

This wasn’t just about displaying some data. We explored how to:

Manage state cleanly with immutable patterns
Trigger UI updates the smart way with Equatable
Optimize list rendering with ListView.builder, keys, and cacheExtent

If you’ve followed along this far, congratulations! You’ve just added another level of skill to your Flutter toolbox. But we have a lot more work to do if we want to create the most complete and efficient Pokédex. In the next part, we will cover the pagination feature. Stay tuned!

If you enjoyed this article and want to stay connected, feel free to connect with me on LinkedIn.

If you'd like to dive deeper into the code and contribute to the project, visit the repository on GitHub.

Was this guide helpful? Consider buying me a coffee!☕️ Your contribution goes a long way in fuelling future content and projects. Buy Me a Coffee.

Feel free to reach out if you have any questions or need further guidance. Also, I would love to see if you have any ideas for the next parts. What features would you like to add on this Pokémon journey?

Flutter Flip Card Animation

Thanasis Traitsis — Sun, 02 Feb 2025 15:41:53 +0000

Welcome fellow Flutter developers! Today, we’re diving into something really exciting: building a flip card animation from scratch. You know those satisfying card-flip effects you see in card board-games and bank applications? We'll create that using nothing but Flutter's built-in animation tools. No external packages needed! And don't worry, this is not an ordinary "copy-paste the code" article. We'll break down the animation principles that make this effect work, giving you the knowledge to create not just this flip animation, but any custom animation your app needs. Ready to upgrade your Flutter apps? Let's start by answering a question that I think you are all wondering.

Why No Packages?

There are plenty of packages in Flutter that can help you create a flip animation in no time. But when you build it yourself, you gain a much better understanding of how animations work under the hood in Flutter. Plus, building it from scratch means you have full control and flexibility over the animation. You can customize it in ways that might not be possible with pre-built solutions.

Now that we got that out of the way, time to build our foundation. We will use a very simple UI because we want to focus on the animation.

The UI Setup

Before diving into animations, let's create the basic building blocks of our card. We'll start with a simple card component that will represent the front face of the card.

The FrontCard widget, is just a basic card layout with a title and some placeholder text:

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

  @override
  Widget build(BuildContext context) {
    return Container(
      margin: EdgeInsets.symmetric(horizontal: 20),
      padding: EdgeInsets.all(20),
      decoration: BoxDecoration(
          border: Border.all(
            width: 2,
            color: Colors.black,
          ),
          color: const Color.fromARGB(255, 164, 215, 235),
          borderRadius: BorderRadius.circular(10)),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        mainAxisSize: MainAxisSize.min,
        children: [
          Text(
            "💳 Flip the card",
            style: TextStyle(
              fontSize: 24,
              fontWeight: FontWeight.bold,
            ),
          ),
          SizedBox(
            height: 20,
          ),
          Text(
              "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting."),
        ],
      ),
    );
  }
}

The next step would be creating our CardContainer widget inside our Home Screen to properly position this card. As I said, we will keep the UI as simple as possible.

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: CardContainer(),
      )
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Container(
      child: FrontCard(),
    );
  }
}

The Basic Logic

Let's build out the core mechanics of our flip card feature. Think of it like setting up a basic two-sided playing card - we can't see both sides at once, but we need to be able to switch between them.

First, we'll make a BackCard widget that mirrors our FrontCard structure but with different content and styling. This gives us a clear visual distinction between the front and back states of our card.

With both card faces ready, we need a way to switch between them. We'll transform our CardContainer into a stateful widget that tracks which side is currently visible using a boolean flag. When a user taps the card, we'll toggle between the front and back faces.

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

  @override
  State<CardContainer> createState() => _CardContainerState();
}

class _CardContainerState extends State<CardContainer> {
  bool isFront = true;

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () {
        setState(() {
          isFront = !isFront;
        });
      },
      child: Container(
        child: isFront ? FrontCard() : BackCard(),
      ),
    );
  }
}

Flip Animation

Enough with the boring part, don't you think? Now that we’ve established the basic logic for toggling between the front and back sides of our card, let’s take things to the next level by adding a smooth flip animation. Rather than instantly switching between the two card faces, we’ll implement a visually engaging transition that mimics the natural motion of a card flipping through space.

In this section, we’ll break down the animation mechanism step by step, explain how the code works, and highlight the key parts that bring the flip animation to life.

Animation Controller

To bring our card flip animation to life, we need an AnimationController. This is the backbone of the animation mechanism in Flutter, giving us complete control over how and when the animation plays. With a controller we can manage:

The duration of the animation.
The flow of the animation. For example, we can start, stop, reverse, or repeat the animation as needed.
Synchronization with the screen. By using the vsync keyword, we ensure that the animation we build is tied with the screen's refresh rate system.
Every single value of the animation from the beginning to the very end. The controller has a range of values from 0 to 1, pointing the start and the finish of the animation, giving us full access of the whole proccess.

In our case, we will use our AnimationController to rotate the FrontCard 180°, but first we need to initialize it.

late AnimationController _cardFlipController;

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

    _cardFlipController = AnimationController(
      duration: const Duration(seconds: 2), // Animation lasts 2 seconds
      vsync: this, // Syncs with the screen refresh rate
    );
  }

At this point, you might see an error on your screen because of the this keyword in the vsync parameter. If your editor seems confused, don’t worry, this is a common issue. Essentially, your program is saying, "Okay, what the f...k is this?"

Relax, dear editor. We can fix this pretty easily by adding a mixin to our class:

class _CardContainerState extends State<CardContainer>
    with SingleTickerProviderStateMixin {
        ...
    }

Now, if you’re feeling ambitious and want multiple animations in the same widget, just remove the word "Single" from the mixin, and you’re good to go. (Yes, it’s that easy!)

Animation Setup

With the AnimationController set up, we are ready to build the actual animation. This is where Tween comes into play. The Tween help us provide the actual values of our animation. Remember in the previous section, where we said that we can define the values from the beginning to the end? This is the place where we can set these values. In our case, we need to start from 0°, and produce half a circle, which means 180°.

late AnimationController _cardFlipController;

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

    _cardFlipController = AnimationController(
      duration: const Duration(seconds: 2), // Animation lasts 2 seconds
      vsync: this, // Syncs with the screen refresh rate
    );

    _cardFlipAnimation = Tween(
      begin: 0.0, // ---> 0°
      end: pi, // ---> 180°
    ).animate(_cardFlipController); // Place the animation controller here
  }

But wait, what is this pi? Thought you never ask... TIME FOR SOME MATHS!

Why Do We Rotate the Card to π?

The value of π radians (equivalent to 180°) represents half of a full rotation. By transitioning to this value, we create the illusion of flipping the card over to reveal its back side. This provides the visual "turning" motion that feels natural.

We have access to this value by importing the dart:math

import 'dart:math' show pi;

Perfect, now all that's left, is updating our UI, so we can apply this amazing animation.

Updating UI

Connecting the animation logic with the UI, will not work with the simple widgets. We need something specifically for this job. Enter the Transform widget, which allows us to manipulate the visual properties of our card, like its position, size, and most importantly—its rotation.

But in order to visualize our animation, we will need another Widget, the AnimationBuilder which will recreate the UI based on the animation. This widget listens to changes in the animation’s value and rebuilds the UI at every frame, ensuring the flip appears smooth and fluid.

Here’s how it all comes together:

@override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () {
        if (isFront) {
          _cardFlipController.forward();
        }
      },
      child: AnimatedBuilder(
        animation: _cardFlipAnimation,
        builder: (context, child) {
          return Transform(
            alignment: Alignment.center,
            transform: Matrix4.identity()
              ..setEntry(3, 2, 0.0012) // Perspective for the realistic flip of the card
              ..rotateY(
                _cardFlipAnimation.value,
              ),
            child: child,
          );
        },
        child: isFront
            ? FrontCard()
            : BackCard(),
      ),
    );
  }

I know that the Transform widget, might look a bit confusing to you, so let's break it down line by line.

Alignment.center: This ensures the card rotates around its center point. Without this, the rotation might pivot from an awkward position, like the top-left corner.
setEntry: Adds a perspective effect, simulating 3D depth. Without this line, the card flip would look flat, as if it were rotating in 2D space.
rotateY: Rotates the card along the Y-axis based on the animation progress. This line drives the actual flipping motion.

The image below, can help you visualize everything we discussed above:

Completing the animation - Switching to BackCard

Our flip animation is looking amazing! However, there's one last thing that needs to be fixed. We only ever see the FrontCard. Even though the animation flips smoothly, the back side never appears because we never swap the UI to display the BackCard.

To achieve this swap seamlessly, we need to find the most efficient point in time during the animation, and change our two widgets. If you think about it, there is a very specific moment, where we cannot see the face of the card, because it is turned sideways. That's our chance to act!

How Do We Implement This?

We use an animation listener on our AnimationController to detect when the animation reaches its halfway point. When it does, we toggle the isFront boolean.

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

  @override
  State<CardContainer> createState() => _CardContainerState();
}

class _CardContainerState extends State<CardContainer>
    with SingleTickerProviderStateMixin {
  late AnimationController _cardFlipController;
  late Animation<double> _cardFlipAnimation;
  bool isFront = true;

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

    _cardFlipController = AnimationController(
      duration: const Duration(seconds: 1),
      vsync: this,
    );

    _cardFlipAnimation = Tween(
      begin: 0.0,
      end: pi,
    ).animate(_cardFlipController);

    // Add a listener to the animation controller
    _cardFlipController.addListener(() {
      // Check if animation is at halfway point (π / 2)
      if (_cardFlipController.value >= 0.5 && isFront) {
        setState(() {
          isFront = false; // Switch to back card
        });
      } else if (_cardFlipController.value < 0.5 && !isFront) {
        setState(() {
          isFront = true; // Switch to front card
        });
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () {
        if (isFront) {
          _cardFlipController.forward();
        } else {
          _cardFlipController.reverse();
        }
      },
      child: AnimatedBuilder(
        animation: _cardFlipAnimation,
        builder: (context, child) {
          return Transform(
            alignment: Alignment.center,
            transform: Matrix4.identity()
              ..setEntry(3, 2, 0.0012)
              ..rotateY(
                _cardFlipAnimation.value,
              ),
            child: child,
          );
        },
        child: isFront
            ? FrontCard()
            : Transform(
                alignment: Alignment.center,
                transform: Matrix4.identity()
                  ..setEntry(3, 2, 0.0012)
                  ..rotateY(pi), // Rotate 180° for the starting position of the back card
                child: BackCard(),
              ),
      ),
    );
  }
}

Before we move on, let’s address one final detail. If you look at the code, you'll notice that when displaying the BackCard, we apply an additional 180° rotation:

Transform(
    alignment: Alignment.center,
    transform: Matrix4.identity()
        ..setEntry(3, 2, 0.0012)
        ..rotateY(pi), // Rotate 180° for the starting position of the back card
        child: BackCard(),
        ),

Why is this necessary?

Since our animation only rotates the card from 0 to π (180°), we need to ensure that the BackCard is correctly oriented when it appears.

Without this extra rotation, the BackCard would appear upside down when it replaces the FrontCard. By pre-rotating the BackCard by π (180°), we align it properly so that when it becomes visible, it appears in the correct orientation.

Wrapping it up

And there you have it! You’ve successfully developed and fully understand how to create a smooth and realistic flip animation in Flutter. More importantly, you now grasp the fundamentals of 3D transformations, perspective effects, and animation control.

With this knowledge, you can level up your application by incorporating this awesome effect into any UI element like flashcards, game mechanics, or stylish flipping menus.

Buuuuut before you go...allow me to add one last thing to this tutorial. I would like to include everything around this flip animation, so whenever you step into something challenging while implementing something similar, this would be the perfect place to jump back into and find the solution you need. I promise it's the last topic we cover.

Card Views with Different Heights – The Asymmetric Flip

This is a pretty special case. You will almost never need an implementation like this in a typical app. However, if you ever find yourself needing an asymmetric card flip animation, where the front and back of the card have different heights, this section has you covered.

I know what you’re thinking: "Why would anyone need this?" Well, trust me, there are people out there desperately looking for this solution (I was one of them).

The Problem

Normally, a card flip animation assumes that both sides of the card are the same size. However, in some UI designs, the back card might be larger because it contains more content. This creates an issue:

If we use a fixed height, one side might be cut off.
If we let the card resize mid-flip, the content above and below the card will move everytime the user flips the card, providing a very bad user experience to the user.

The solution? We need to measure both cards' heights before displaying them and then set a consistent maximum height for the animation.

The Solution

Here is how we solve our asymmetric problem in a few simple steps:

Create GlobalKeys for both Front and Back widgets, so you can measure their heights
Store the maximum height inside the maxHeight variable
Use OffStage widget in order to build the cards (so we can measure their heights), but without displaying them to the user

Here's how the final code will look like:

import 'package:card_rotation/card/back_card.dart';
import 'package:card_rotation/card/front_card.dart';
import 'package:flutter/material.dart';
import 'dart:math' show pi;

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

  @override
  State<CardContainer> createState() => _CardContainerState();
}

class _CardContainerState extends State<CardContainer>
    with SingleTickerProviderStateMixin {
  late AnimationController _cardFlipController;
  late Animation<double> _cardFlipAnimation;
  bool isFront = true;

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

    _cardFlipController = AnimationController(
      duration: const Duration(seconds: 1),
      vsync: this,
    );

    _cardFlipAnimation = Tween(
      begin: 0.0,
      end: pi,
    ).animate(_cardFlipController);

    _cardFlipController.addListener(() {
      if (_cardFlipController.value >= 0.5 && isFront) {
        setState(() {
          isFront = false;
        });
      } else if (_cardFlipController.value < 0.5 && !isFront) {
        setState(() {
          isFront = true;
        });
      }
    });

    // Measure the heights after the first layout phase
    WidgetsBinding.instance.addPostFrameCallback((_) {
      measureHeights();
    });
  }

  final GlobalKey _frontCardKey = GlobalKey(); // GlobalKey for FrontCard
  final GlobalKey _backCardKey = GlobalKey(); // GlobalKey for BackCard

  late double frontCardHeight;
  late double backCardHeight;
  double? maxHeight;

  @override
  void dispose() {
    _cardFlipController.dispose();
    super.dispose();
  }

  // Function to measure heights of FrontCard and BackCard
  void measureHeights() {
    final frontRenderBox =
        _frontCardKey.currentContext?.findRenderObject() as RenderBox?;
    final backRenderBox =
        _backCardKey.currentContext?.findRenderObject() as RenderBox?;

    if (frontRenderBox != null && backRenderBox != null) {
      setState(() {
        frontCardHeight = frontRenderBox.size.height;
        backCardHeight = backRenderBox.size.height;
        maxHeight =
            frontCardHeight > backCardHeight ? frontCardHeight : backCardHeight;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Offstage(
          child: FrontCard(
            key: _frontCardKey, // Attach the GlobalKey here
          ),
        ),
        Offstage(
          child: BackCard(
            key: _backCardKey, // Attach the GlobalKey here
          ),
        ),
        SizedBox(
          height: maxHeight,
          child: GestureDetector(
            onTap: () {
              if (isFront) {
                _cardFlipController.forward();
              } else {
                _cardFlipController.reverse();
              }
            },
            child: AnimatedBuilder(
              animation: _cardFlipAnimation,
              builder: (context, child) {
                return Transform(
                  alignment: Alignment.center,
                  transform: Matrix4.identity()
                    ..setEntry(3, 2, 0.0012)
                    ..rotateY(
                      _cardFlipAnimation.value,
                    ),
                  child: child,
                );
              },
              child: isFront
                  ? FrontCard()
                  : Transform(
                      alignment: Alignment.center,
                      transform: Matrix4.identity()
                        ..setEntry(3, 2, 0.0012)
                        ..rotateY(pi),
                      child: BackCard(),
                    ),
            ),
          ),
        ),
      ],
    );
  }
}

Finally, we have to mention that this is not a space-efficient solution. We create two extra widgets (FrontCard and BackCard) that never actually appear on the screen. Overloading the app with unused UI elements is bad practice and can lead to performance issues, especially in more complex applications. As a developer, your goal should always be to write efficient, scalable code. However, sometimes, special problems require special solutions, and that’s okay as long as you understand the trade-offs.

Conclusion

And there you have it everyone. Another Flutter tutorial has come to an end. I hope this guide helped you find exactly what you were looking for when searching for a Card Flip Animation. We covered everything from the fundamentals of an AnimationController to the explanation of 3D transformations in Flutter. Along the way, we explored perspective effects, UI swapping, and even handling asymmetric card flips, leaving no stone unturned!

Now, you're fully equipped with a solid understanding of Flutter animations. Whether you want to implement a card flip, or even more complex 3D animations, you have all the tools you need to bring your ideas to life. Until we meet again on another coding adventure...Happy Coding!!

If you enjoyed this article and want to stay connected, feel free to connect with me on LinkedIn.

If you'd like to dive deeper into the code and contribute to the project, visit the repository on GitHub.

Was this guide helpful? Consider buying me a coffee!☕️ Your contribution goes a long way in fuelling future content and projects. Buy Me a Coffee.

Feel free to reach out if you have any questions or need further guidance. Cheers to your future Flutter projects!

Flutter Bloc Transformer Events

Thanasis Traitsis — Mon, 30 Dec 2024 10:12:53 +0000

Hey there, Flutter devs! I see you. You've been crafting that new feature, but something feels... off. You know you got the logic right, it's pretty clear in that well-structured code you wrote. Yet somehow, your Bloc events seem to have a mind of their own. Why aren't they behaving the way you know they should?

Don't worry—you're not alone. Today, we're diving into Bloc transformer events. What if I told you that in every Bloc event you build, there is a transformer running behind the scene. And what If I take it a step further and tell you that there are not one but FOUR transformers you can choose from. These little operators can drastically shape how your events are processed, and trust me, they can make or break your flow.

So, it's time for another debugging adventure. Jump back to your code and let's solve the mystery of transformer events. By the end, you'll wonder how you ever lived without them.

Types of Transformer Events

Concurrent

When you create a Bloc and start creating events, concurrent is the transformer working behind the scenes. This is the default behaviour of Bloc. It's a pretty standard way of executing the code and a really convenient one. Every event operate independently, without affecting the behaviour of others.

Think of concurrent events like customers at a café. One customer orders a coffee and enjoys it at their own pace. While enjoying their coffee, another customer places an order without waiting for the first to finish. We can all enjoy our coffee with no problem.

In Bloc:

Multiple events can be processed simultaneously without waiting for the previous one to complete.
Events aren’t bottlenecked—each one is handled as soon as it arrives.

But wait, what if the café has only one chair? Suddenly, things aren’t so smooth. Now, each customer has to wait for the previous one to finish their coffee before placing an order.

Sequential

Events are carried out exactly as they come in thanks to the sequential transformer, but only one at a time. A new event cannot start until the processing of the prior one is complete.

Imagine a tiny espresso bar with just one chair and a single barista. One customer orders, sits, drinks their coffee, and only then can the next customer step up.

In Bloc:

Events queue up and are processed sequentially.
No two events overlap, ensuring a predictable and orderly flow.

Okay now that we get the first two transformers out of the way, it’s time to introduce something that’s a total game-changer—especially for search and autocomplete features.

Restartable

This event is perfect for situations where only the latest event matters. When a new event arrives, it cancels any ongoing ones and immediately starts processing the fresh request.

Now, I want you to imagine that you decide to drink your coffee in the worst café of all time. You sit down, peacefully sipping your hot coffee, enjoying life. Then a new customer appears out of nowhere! Without hesitation, they snatch your cup, kick you out, and start drinking their own coffee.

In Bloc:

If multiple search queries are fired rapidly, only the latest one gets processed.
Any previous events still in progress are cancelled as soon as a new one arrives.

For real-time search, form validation, or any situation where the most recent input is prioritised, this transformer is your best option. Restartable is the best option if the most recent modification is all that matters.

Last but not least, the final transformer event is a really interesting one. Let's talk about the droppable event.

Droppable

This event is really useful when you want to avoid repetitive calls. If an event is already being processed, any new events of the same type are ignored until the first one finishes. Once the running event completes, the next one can be accepted.

Let’s visit one last café. You walk in, eager for a cup of coffee, and you see another person already enjoying their drink. You sit down and start waving to place your order, but no one listens. The staff won’t take your order until the current customer finishes and leaves. Once that last drop is gone, the café is all yours, and the waiters rush to take your order.

In Bloc:

If an event (like fetching data) is already running, new incoming events are ignored.
Once the active event completes, the next event will be accepted.

That's a really useful tools for situations like API calls that shouldn't be interrupted, or maybe for preventing duplicate submissions.

Package & Code

All it takes to unlock this feature is installing a package and writing just ONE line of code. Really, that's all! The rest? Just your regular Bloc setup, nothing special.

First, download this package:

bloc_concurrency : With this package we are able to use all the transformer events with built-in functions.

Now, all you have to do, is jump in the example_bloc.dart file, and change the way you initialize a bloc event. For example, I have a simple counter application, in which I manage the state with a Bloc event.

  TransformerBloc() : super(const TransformerState(count: 0)) {
    on<IncrementPressed>(
      _onIncrement, // By default, it has the concurrent transformer
    );
  }

  Future<void> _onIncrement(
      IncrementPressed event, Emitter<TransformerState> emit) async {
    await Future.delayed(const Duration(seconds: 2));
    emit(state.copyWith(count: state.count + 1));
  }

If I want to change the way I handle this event, by applying sequential transformer for example, all I have to do is this:

  TransformerBloc() : super(const TransformerState(count: 0)) {
    on<IncrementPressed>(
      _onIncrement,
      transformer: sequential(), // Apply this line
    );
  }

Conclusion

Bloc transformer events might look like a hidden detail at first, but as you can see, they can take your state management in a whole new level. And the best part? You only need to add one line in your existing code, and change the entire functionality. How amazing is that?

Now go on my Flutter friends, you are free to explore new code adventures. Next time your Bloc events aren’t behaving quite the way you expected, remember—you’ve got options. Pick the right transformer, like you pick the right café in your hometown that serves the best coffee. 😉 ☕

If you enjoyed this article and want to stay connected, feel free to connect with me on LinkedIn.

If you'd like to dive deeper into the code and contribute to the project, visit the repository on GitHub.

Was this guide helpful? Consider buying me a coffee!☕️ Your contribution goes a long way in fuelling future content and projects. Buy Me a Coffee.

Feel free to reach out if you have any questions or need further guidance. Cheers to your future Flutter projects!

Mastering Custom Widget Themes in Flutter

Thanasis Traitsis — Sat, 05 Oct 2024 06:36:07 +0000

Well hello there Flutter people. It's been a while since my last blog post, but I'm back with something very interesting that will level up your Flutter applications. Today's subject is Custom Widget Themes, a powerful way to manage consistent, reusable styling throughout your app.

Ever found yourself copying and pasting container styles throughout your app? Sure, creating a Stateless Widget might seem like a quick and easy fix, but there's a more clean, maintainable solution hiding in Flutter's theming system.

In this tutorial, we'll explore how to:

Create custom container themes within ThemeData.
Define reusable style variables (colors, text sizes, etc.).
Implement responsive design principles using themes.
Keep your code DRY (Don't Repeat Yourself) and maintainable.

By the time you finish reading this post, you'll have a new tool in your Flutter toolbelt for creating more consistent, scalable UI designs. Let's dive in!

Setting Up Theme Values 🎨

Before we dive into custom container themes, we need to establish a foundation of consistent values that we'll use throughout our application. This approach ensures visual consistency and makes future updates much easier to manage.

Let's create a file and call it app_values.dart. This file will store all our standard values and looks like this:

class AppValues {
  final double smallText = 10.0;
  final double normalText = 12.0;
  final double largeText = 24.0;

  final double pokecardBorderRadius = 20;
  final double pokecardPadding = 10;
}

Next, create a colors.dart file to define our color scheme:

class AppColors {
  final Color grassBackgroundColor;
  final Color grassTextColor;
  final Color grassOutlineColor;

  AppColors({
    required this.grassBackgroundColor,
    required this.grassTextColor,
    required this.grassOutlineColor,
  });

  static final mainColors = AppColors(
    grassBackgroundColor: const Color(0xffcef79f),
    grassTextColor: const Color(0xff2a513f),
    grassOutlineColor: const Color(0xff378e8e),
  );
}

Now, with these two files perfectly setup, it's time to create our ThemeData. Create a file, name it app_theme.dart and include this class:

class AppTheme {
  final AppColors chosenColor;

  AppTheme(
    this.chosenColor,
  );

  ThemeData getTheme() {
    final values = AppValues();

    return ThemeData(
      useMaterial3: true,
      // You can add your own appbar style, background color, primary color etc...
      textTheme: TextTheme(
        titleLarge: TextStyle(
          fontSize: values.largeText,
          color: chosenColor.grassTextColor,
          fontWeight: FontWeight.bold,
        ),
      ),
    );
  }
}

Why This Matters:

Consistent color usage enhances your app's visual coherence.
Using semantic color names (like 'grassBackgroundColor') makes your code more maintainable.
The factory constructor pattern allows for easy theme switching if needed.

By the way, if you are paying attention on the variable names, I think you know what's the main topic of this tutorial...

Custom Theme Extension

Let's dive into the main reason you clicked on this tutorial. The scenario of this application is that I want to showcase every Grass-type Pokémon inside its own card. This card will be the same for every Pokémon, so there is no need to build the same widget continuously. Instead, let’s create a theme to define every Grass-type card:

class GrassTypeTheme extends ThemeExtension<GrassTypeTheme> {
  final Color backgroundColor;
  final Color textColor;
  final Color outlineColor;
  final EdgeInsets cardPadding;
  final BorderRadius cardBorderRadius;

  GrassTypeTheme({
    required this.backgroundColor,
    required this.textColor,
    required this.outlineColor,
    required this.cardPadding,
    required this.cardBorderRadius,
  });
}

That's the foundation of our Theme. What makes this situation particularly noteworthy is the inheritance of the class, because it extends the ThemeExtension. That's the key of the whole tutorial. To properly implement this extension, we need to focus on two critical steps:

Step 1: Implement the copyWith Method

The copyWith method is crucial for our custom theme. It allows us to create new instances of our theme by overriding specific properties. This is useful when you want to create variants or update only a few values dynamically.

Let’s add it to our class:

@override
  ThemeExtension<GrassTypeTheme> copyWith({
    Color? backgroundColor,
    Color? textColor,
    Color? outlineColor,
    EdgeInsets? cardPadding,
    BorderRadius? cardBorderRadius,
  }) {
    return GrassTypeTheme(
      backgroundColor: backgroundColor ?? this.backgroundColor,
      textColor: textColor ?? this.textColor,
      outlineColor: outlineColor ?? this.outlineColor,
      cardPadding: cardPadding ?? this.cardPadding,
      cardBorderRadius: cardBorderRadius ?? this.cardBorderRadius,
    );
  }

Step 2: Implement the lerp Method

The lerp method (linear interpolation) is essential when animating theme changes or transitioning between different theme states. It helps Flutter animate changes smoothly when switching themes.

Here’s how you can implement it:

 @override
  ThemeExtension<GrassTypeTheme> lerp(
      covariant ThemeExtension<GrassTypeTheme>? other, double t) {
    if (other is! GrassTypeTheme) return this;
    return GrassTypeTheme(
      backgroundColor: Color.lerp(backgroundColor, other.backgroundColor, t)!,
      textColor: Color.lerp(textColor, other.textColor, t)!,
      outlineColor: Color.lerp(outlineColor, other.textColor, t)!,
      cardPadding: EdgeInsets.lerp(cardPadding, other.cardPadding, t)!,
      cardBorderRadius:
          BorderRadius.lerp(cardBorderRadius, other.cardBorderRadius, t)!,
    );
  }

With these two methods (copyWith and lerp) in place, your custom theme is now complete and ready to be used!

Completing The App Theme 🔧

You are one step away of completing the most responsive and maintainable application setup you ever created. We just need to add the extension we just built into our ThemeData. Here's the code:

class AppTheme {
  final AppColors chosenColor;

  AppTheme(
    this.chosenColor,
  );

  ThemeData getTheme() {
    final values = AppValues();

    return ThemeData(
      useMaterial3: true,
      textTheme: TextTheme(
        titleLarge: TextStyle(
          fontSize: values.largeText,
          color: chosenColor.grassTextColor,
          fontWeight: FontWeight.bold,
        ),
      ),
      // There is the ThemeExtension we created
      extensions: <ThemeExtension<dynamic>>[
        GrassTypeTheme(
          backgroundColor: chosenColor.grassBackgroundColor,
          textColor: chosenColor.grassTextColor,
          outlineColor: chosenColor.grassOutlineColor,
          cardBorderRadius: BorderRadius.circular(values.pokecardBorderRadius),
          cardPadding: EdgeInsets.all(values.pokecardPadding),
        ),
      ],
    );
  }
}

The power of our theming system lies in its flexibility. Since the extension property is a List, you can define multiple themes to suit your needs. With our foundation in place, all that's left is to create a Widget that leverages our carefully crafted theme.

class CustomContainer extends StatelessWidget {
  final String text;
  final String img;

  const CustomContainer({
    super.key,
    required this.text,
    required this.img,
  });

  @override
  Widget build(BuildContext context) {
    final containerTheme = Theme.of(context).extension<GrassTypeTheme>();

    return Container(
      width: 300,
      height: 200,
      padding: containerTheme?.cardPadding,
      decoration: BoxDecoration(
        borderRadius: containerTheme?.cardBorderRadius,
        color: containerTheme?.backgroundColor,
        border: Border.all(
          width: 4,
          color: containerTheme!.outlineColor,
        ),
      ),
      child: Stack(
        alignment: Alignment.bottomLeft,
        children: [
          Positioned(
            left: 100,
            right: 0,
            top: 0,
            bottom: 0,
            child: Image.network(img),
          ),
          Text(
            text,
            style: Theme.of(context).textTheme.titleLarge,
          ),
        ],
      ),
    );
  }
}

When you implement this widget in your app, you'll see the theme come to life, automatically adapting to any theme changes you make. For now, let's enjoy our beautiful Bulbasaur card that we created with such quality code.

Conclusion

And there you have it! We've unlocked a new level of customisation that goes much beyond basic color schemes by utilising Flutter's ThemeExtension. This approach enables us to create rich, deeply customizable themes that can hold any design property we need - from padding and border radius to complex color palettes and more.

The next time you find yourself reaching for hard-coded styles or repetitive design code, consider leveraging ThemeExtension to create a more elegant, maintainable solution. Happy theming!

If you enjoyed this article and want to stay connected, feel free to connect with me on LinkedIn.

If you'd like to dive deeper into the code and contribute to the project, visit the repository on GitHub.

Was this guide helpful? Consider buying me a coffee!☕️ Your contribution goes a long way in fuelling future content and projects. Buy Me a Coffee.

Feel free to reach out if you have any questions or need further guidance. Cheers to your future Flutter projects!

How to switch themes in Flutter using BLoC

Thanasis Traitsis — Fri, 03 May 2024 20:25:47 +0000

Welcome to the ultimate guide on how to switch themes in your Flutter application using BLoC. In this article, we're embarking on a journey to master the art of seamlessly toggling between light and dark themes. By leveraging the power of the BLoC pattern, we'll completely separate the theme-switching logic from the UI components, ensuring maintainability and flexibility as your app evolves.

But wait, this is not your ordinary "theme-switching" article. Before we dive into the intricacies of toggling between themes, let's lay a solid foundation by exploring the entire theming process from the ground up. We'll start by learning how to create our own custom themes, diving into clean architecture essentials on how to meticulously separate the fonts, colors, and everything in between.

So, let's dive right in and begin crafting our custom light and dark themes, shall we? We'll gently guide our themes onto the canvas of our Flutter app. Remember, there are no mistakes, only happy little themes waiting to emerge.

Setting up the custom App Theme

To establish a clean and organized codebase, we'll begin by setting up our custom app theme structure. Here's a suggested folder structure:


📦lib
 ┗ 📂config
    ┗ 📂themes
 ┗ 📂core
    ┣ 📂constants
    ┗ 📂usecases

Inside the constants, lets create two files.

1. constants.dart: Here you can add any constant variable, for example, the name of your Google Font.

// ========================================================
// Font Family
const String fontFamilyName = 'Manrope';

// ========================================================
// Spacing
const double paragraphSpacing = 10.0;
const double buttonGap = 20.0;

2. sizes.dart: In this file, we gather all values related to sizing aspects of our application, including font sizes and any other dimensions that play a crucial role in defining the visual appearance and layout.

class AppValues {
  // ========================================================
  // Font Size
  final double smallText = 14.0;
  final double normalText = 16.0;
  final double largeText = 20.0;
  final double appBarText = 22.0;
}

Now, let's focus on defining the color palette of our application. Inside the themes folder, we'll create a dedicated file for managing colors. Here's our colors.dart file:

class AppColors {
  final Color whiteColor;
  final Color blackColor;
  final Color backgroundColor;
  final Color textColor;
  final Color primaryColor;

  AppColors({
    required this.whiteColor,
    required this.blackColor,
    required this.backgroundColor,
    required this.textColor,
    required this.primaryColor,
  });

  // ========================================================
  // Main color theme
  static final mainColors = AppColors(
    whiteColor: const Color(0xffFFFFFF),
    blackColor: const Color(0xff000000),
    backgroundColor: const Color.fromARGB(255, 255, 255, 255),
    textColor: const Color.fromARGB(255, 55, 56, 56),
    primaryColor: const Color.fromARGB(255, 90, 154, 192),
  );

  // ========================================================
  // Dark color theme
  static final darkColors = AppColors(
    whiteColor: const Color(0xff000000),
    blackColor: const Color(0xffFFFFFF),
    backgroundColor: const Color.fromARGB(255, 55, 56, 56),
    textColor: const Color.fromARGB(255, 255, 255, 255),
    primaryColor: const Color.fromARGB(255, 154, 169, 178),
  );
}

Custom App Theme

With all the core values being set, it's time to bring our app theme to life. Within the themes folder, let's create a new file named app_theme.dart. This file will have a class that returns a ThemeData based on the colors we choose. Our goal with this class is to keep the core structure of the app theme intact while allowing for dynamic color changes. This approach ensures that any theme switch seamlessly updates the colors of our application without impacting text or container sizes.

class AppTheme {
  final AppColors chosenColor;

  AppTheme(
    this.chosenColor,
  );

  ThemeData getTheme() {
    final sizes = AppValues();

    return ThemeData(
      fontFamily: fontFamilyName,
      colorScheme: ColorScheme.fromSeed(
        background: chosenColor.backgroundColor,
        seedColor: chosenColor.primaryColor,
        primary: chosenColor.primaryColor,
      ),
      appBarTheme: AppBarTheme(
        backgroundColor: chosenColor.primaryColor,
        foregroundColor: chosenColor.backgroundColor,
        titleTextStyle: TextStyle(
          fontFamily: fontFamilyName,
          fontSize: sizes.appBarText,
          color: chosenColor.whiteColor,
          fontWeight: FontWeight.w500,
        ),
      ),
      textTheme: TextTheme(
        bodyMedium: TextStyle(
          color: chosenColor.textColor,
          fontSize: sizes.normalText,
          fontFamily: fontFamilyName,
        ),
        headlineLarge: TextStyle(
          color: chosenColor.textColor,
          fontSize: sizes.largeText,
          fontFamily: fontFamilyName,
        ),
      ),
      filledButtonTheme: FilledButtonThemeData(
        style: ButtonStyle(
          backgroundColor:
              MaterialStateProperty.all<Color>(chosenColor.primaryColor),
          foregroundColor:
              MaterialStateProperty.all<Color>(chosenColor.whiteColor),
          textStyle: MaterialStateProperty.all<TextStyle>(
            TextStyle(
              fontSize: sizes.smallText,
              fontFamily: fontFamilyName,
            ),
          ),
        ),
      ),
      switchTheme: SwitchThemeData(
        thumbColor: MaterialStateProperty.all<Color>(chosenColor.primaryColor),
        overlayColor:
            MaterialStateProperty.all<Color>(chosenColor.backgroundColor),
        trackColor:
            MaterialStateProperty.all<Color>(chosenColor.backgroundColor),
        trackOutlineColor:
            MaterialStateProperty.all<Color>(chosenColor.backgroundColor),
      ),
    );
  }
}

And that's pretty much it. That's how you create a custom theme. Now, all you have to do, is set this theme inside the main.dart file, where the MaterialApp Widget is located.

@override
  Widget build(BuildContext context) {
    return MaterialApp(
        debugShowCheckedModeBanner: false,
        theme: AppTheme(AppColors.mainColors).getTheme(),
        home: HomePage(),
    );
  }

Switching themes

Before diving into building our state management system to control the theme, we'll need to download some essential packages first. Here's the list:

These packages will equip us with the essential tools to effectively manage theme switching functionality in our Flutter application. Additionally, they enable us to store and retrieve the user's preferred theme, ensuring a seamless and personalized experience for each user.

Setting up the BLoC state manager

In this project, we're simplifying our state management strategy by utilizing theme_bloc and theme_event. Instead of dealing with multiple theme states, we'll streamline our implementation by representing the theme status with a single boolean value. This is how the theme_bloc.dart will look like:

// if bool = true -----> the Theme is dark 
// if bool = false -----> the Theme is light 

class ThemeBloc extends Bloc<ThemeEvent, bool> {
  ThemeBloc() : super(false) {

    // execute this event when the app starts
    on<SetInitialTheme>(
      (event, emit) async {
        bool hasThemeDark = await isDark();

        emit(hasThemeDark);
      },
    );

    // toggle the app theme
    on<ChangeTheme>(
      (event, emit) async {
        bool hasThemeDark = await isDark();

        emit(!hasThemeDark);
        setTheme(!hasThemeDark);
      },
    );
  }
}

Future<bool> isDark() async {
  final SharedPreferences sharedPreferences =
      await SharedPreferences.getInstance();

  return sharedPreferences.getBool('isDark') ?? false;
}

Future<void> setTheme(bool isDark) async {
  final SharedPreferences sharedPreferences =
      await SharedPreferences.getInstance();

  sharedPreferences.setBool('isDark', isDark);
}

The code of theme_event.dart is as simple as possible. Here are the three lines of code:

abstract class ThemeEvent {}

class SetInitialTheme extends ThemeEvent {}

class ChangeTheme extends ThemeEvent {}

Changes in the main.dart, to initialize the BLoC

In our main.dart file, we're taking the first steps to integrate our BLoC state management system seamlessly into our application. At the heart of it all, is the runApp function, where we set up a BlocProvider to supply our ThemeBloc to the entire app. Within this provider, we ensure that the SetInitialTheme() event is executed right from the start, setting the tone for our app's initial theme selection.

void main() {
  runApp(
    BlocProvider(
      create: (context) => ThemeBloc()
        ..add(
          SetInitialTheme(),
        ),
      child: const MainApp(),
    ),
  );
}

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

  @override
  Widget build(BuildContext context) {
    return BlocBuilder<ThemeBloc, bool>(
      builder: (context, state) {
        return MaterialApp(
          debugShowCheckedModeBanner: false,
          theme: state
              ? AppTheme(AppColors.darkColors).getTheme()
              : AppTheme(AppColors.mainColors).getTheme(),
          home: const HomeScreen(),
        );
      },
    );
  }
}

By looking closely in the MaterialApp, we can see that we're dynamically choosing between the dark and light themes based on the current state of our ThemeBloc. If the state indicates that the dark theme is active, we use the dark theme defined in AppTheme, otherwise, we default to the light theme. This ensures that our app's appearance adjusts in real-time according to the user's selected theme preference.

Implement the switch functionality

To finalize our theme-switching functionality, we'll implement the ChangeTheme() event. In our application, we'll use a Switch widget to provide a visual representation of theme toggling. Here's how we can integrate it into our app:

  AppBar(
    title: Text(title),
    actions: [
      BlocBuilder<ThemeBloc, bool>(
        builder: (context, state) {
          return Switch(
            value: state,
            onChanged: (bool val) {
              context.read<ThemeBloc>().add(ChangeTheme());
            },
          );
        },
      ),
    ],
  )

Conclusion

There you go everybody! Indeed, theme switching in Flutter becomes effortless with the BLoC pattern. By decoupling the theme logic from the UI components, BLoC enables smooth and efficient management of theme changes. With this pattern, we can seamlessly toggle between themes, ensuring a consistent and visually appealing user experience across our Flutter applications. Also, let's not forget that we've demonstrated the flexibility of creating custom themes, allowing us to break away from the traditional light and dark themes provided by Flutter.

If you enjoyed this article and want to stay connected, feel free to connect with me on LinkedIn.

If you'd like to dive deeper into the code and contribute to the project, visit the repository on GitHub.

Was this guide helpful? Consider buying me a coffee!☕️ Your contribution goes a long way in fuelling future content and projects. Buy Me a Coffee.

Feel free to reach out if you have any questions or need further guidance. Cheers to your future Flutter projects!