Stop mutating views. Describe them instead.

You have spent years building a mental model where a view exists, you keep a handle to it, and you change it over time. A UILabel or a TextView is an object that lives on screen; you set its .text and the pixels follow. This is imperative UI: a sequence of commands that mutate a long-lived tree of view objects.

Flutter is declarative. You write a function that, given the current data, returns a description of what the screen should look like right now. You never hold a description and edit it later — when the data changes, you throw the old description away and build a fresh one. The framework figures out the minimal set of real changes to make on screen.

If you have written SwiftUI or Jetpack Compose, you already know this feeling — Flutter is the same family of idea, and everything you learned there transfers. If you have not, the adjustment is real but short. The single sentence to hold onto: you describe the UI as a function of your data, and you change the UI only by changing the data.

On native platforms you have a zoo of concepts: views, view controllers, layout constraints, storyboards or XML, and a separate world for padding and centring. Flutter collapses almost all of it into a single noun: the widget. A button is a widget. So is the text on it. So is the padding around it, the centre alignment, the row it sits in, and the whole screen.

Crucially, structure and styling that you think of as properties on other platforms are widgets here. You don't set a padding attribute — you wrap your widget in a Padding widget. You don't set an alignment flag — you wrap it in Center. UI is built by composition: small widgets nested inside bigger ones, forming a tree.

Center(                         // centres its child
  child: Padding(               // adds space around its child
    padding: EdgeInsets.all(16),
    child: Text(                // draws a string
      'Hello, Flutter',
      style: TextStyle(fontSize: 24),
    ),
  ),
)

Read that as a tree: Center contains Padding contains Text. Each widget has exactly one job. On iOS or Android you might express "centred, padded text" with constraints or a layout file; in Flutter you express it by nesting three single-purpose widgets. This feels verbose at first and becomes strangely pleasant: everything is explicit and local.

There are two flavours of widget, and the distinction runs through the whole framework: StatelessWidget (a description that never changes once built — an icon, a label, a static row) and StatefulWidget (a widget that keeps some mutable data and can rebuild itself when that data changes — a checkbox, a form field, an animating spinner). Modules 1 and 2 are dedicated to each; for now just know both exist.

Here is the apparent paradox. Widgets are immutable and get rebuilt constantly. Yet a text field keeps what you typed, a scroll list keeps its position, and an animation doesn't restart on every frame. If the widgets are thrown away, where does that memory live?

The answer is that "the UI" is not one tree but three, and they play different roles. You only ever write the first one directly.

The flow: you produce a new widget tree. Flutter walks it against the existing element tree, and for each position asks a cheap question — "is the new widget the same kind as the old one here?" If yes, it keeps the element (and its State, and its render object) and just updates them with the new configuration. If no, it tears that element down and builds a fresh one. Your typed text survives because its element survived, even though the widget describing it was replaced.

You will not manipulate elements or render objects for a long time — possibly ever. But this model pays off the moment something surprises you: a form that mysteriously resets, an animation that jumps, a list item showing the wrong data after reordering. Every one of those is Flutter matching the wrong element to a widget. The fix is a key, and it will make sense because you know these trees exist (module 11).

Dart will feel immediately familiar — it sits squarely between Swift and Kotlin. Curly braces, classes, async/await, sound null safety. You can read it on day one; here are the handful of things worth pointing at explicitly.

Two Dart-specific things earn their keep. First, named parameters in braces. Most widget constructors take named arguments, often required ones — this is why widget code reads like a labelled form rather than a positional guessing game:

class Badge {
  final String label;
  final int count;
  Badge({required this.label, this.count = 0});
}

// call site — order-free, self-documenting
Badge(label: 'Inbox', count: 12);
Badge(label: 'Drafts');   // count defaults to 0

Second, const constructors. If a widget's configuration is fully known at compile time, you can construct it with const. Flutter then knows that widget can never differ between builds and skips rebuilding its subtree entirely. Sprinkling const on your static widgets is the cheapest performance win in the framework — the analyzer will even nag you to add it.

Icon(Icons.star)
// rebuilt & re-compared
// every single build

const Icon(Icons.star)
// built once, reused,
// subtree rebuild skipped

A StatelessWidget is a widget whose appearance depends only on the configuration it was given. Give it the same inputs and it always looks the same; it has no memory of its own. Think of a component that shows a user's name and avatar — hand it a User, it draws that user, done. Most of the widgets you write will be stateless.

class Greeting extends StatelessWidget {
  final String name;
  const Greeting({super.key, required this.name});

  @override
  Widget build(BuildContext context) {
    return Text('Hello, $name');
  }
}

// used like any other widget
const Greeting(name: 'Ada')

Three things to notice. The data (name) is final — a stateless widget's fields never change; to show a different name you build a new Greeting. The constructor is const, so this widget is cheap. And build is the one method that matters: it returns a description, and Flutter calls it whenever this widget is inserted or its parent hands it new configuration.

Compare it to a native custom view. There, you'd have an initialiser, outlets, and an update() you call by hand when the model changes. Here there is no update method and no outlets — just build, re-run for you. The mental weight of "did I refresh every view after the model changed?" is simply gone.

class PriceTag extends StatelessWidget {
  final double price;
  final String currency;
  const PriceTag({
    super.key,
    required this.price,
    required this.currency,
  });

  @override
  Widget build(BuildContext context) {
    return Text('\$${price.toStringAsFixed(2)} $currency');
  }
}

When a widget must remember something between builds — a counter, whether a switch is on, the text in a field — it becomes a StatefulWidget. This comes as a pair of classes, which trips everyone up for a minute, so let's be precise about why.

The StatefulWidget itself is still immutable and disposable, exactly like a stateless one — it's rebuilt constantly. The mutable data can't live there. So it lives in a separate, long-lived State object, which Flutter keeps attached to the element (tree two, from §3) across rebuilds. The widget is the blueprint; the State is the memory.

class Counter extends StatefulWidget {
  const Counter({super.key});
  @override
  State<Counter> createState() => _CounterState();
}

class _CounterState extends State<Counter> {
  int _count = 0;          // the mutable memory

  void _increment() {
    setState(() {        // tell Flutter state changed
      _count++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return TextButton(
      onPressed: _increment,
      child: Text('Count: $_count'),
    );
  }
}

The critical rule: mutate state only inside setState. Writing _count++ on its own changes the variable but never tells the framework to rebuild, so the screen freezes on the old value — the number-one beginner bug. setState does two things: it runs the closure (where you change the data) and it marks this element as needing a rebuild, so Flutter re-runs build before the next frame.

Why the two-class split, again? Because the widget is thrown away and rebuilt, but your _count must survive that. Putting it in State, which Flutter pins to the durable element, is what lets the number persist while the Counter widget describing it is replaced on every frame.

class _FavState extends State<Fav> {
  bool _on = false;

  @override
  Widget build(BuildContext context) {
    return IconButton(
      icon: Icon(_on ? Icons.favorite
                       : Icons.favorite_border),
      onPressed: () => setState(() => _on = !_on),
    );
  }
}

Flutter has no auto-layout, no constraint solver, no flexbox engine to reason about. Its layout is a single pass with one rule, repeated down and up the tree: constraints go down, sizes go up, and the parent sets position. Memorise that sentence; it explains every layout you'll ever build.

Concretely: a parent tells each child the minimum and maximum width and height it may take ("you may be 0–360 wide and 0–800 tall"). The child picks its own size within that, and tells the parent. The parent then decides where to put the child. A widget never chooses its own position and never sees anything outside its own constraints.

The two workhorses are Row (lay children out horizontally) and Column (vertically). They come from the same family as flexbox, with two alignment axes:

Row(
  mainAxisAlignment: MainAxisAlignment.spaceBetween,  // along the row
  crossAxisAlignment: CrossAxisAlignment.center,    // across it
  children: [
    const Icon(Icons.menu),
    const Text('Inbox'),
    Icon(Icons.search),
  ],
)

When a child should absorb the leftover space, wrap it in Expanded (take all you can) or Flexible (take up to what you need). A Row with a fixed icon and an Expanded title is the bread and butter of app bars.

Now the rite of passage. Put a very long Text, or a fixed-width box, in a Row that isn't wide enough, and you meet this:

Read it the way you now read a compiler error. A Row tried to place children wider than the width it was handed. The Row can't grow (its parent didn't allow it), so it reports the overflow rather than silently clipping. The fix is always one of: let a child flex (Expanded), let the content wrap or shrink, or make the parent scrollable. Overflow isn't a bug in Flutter — it's Flutter refusing to guess what you meant.

Row(
  children: [
    const Icon(Icons.folder),
    const SizedBox(width: 12),
    Expanded(                       // take the leftover width
      child: Text(
        title,
        overflow: TextOverflow.ellipsis,  // truncate with …
      ),
    ),
    const Icon(Icons.chevron_right),
  ],
)

From §3 you know context is a handle to this widget's spot in the element tree. Its main day-to-day use is looking upward: "what theme applies here?", "how tall is the screen?", "which navigator should I push onto?". Flutter answers by walking up the element tree from your context until it finds the nearest ancestor of the right kind. That's the SomeThing.of(context) idiom.

Widget build(BuildContext context) {
  final theme = Theme.of(context);        // nearest Theme above
  final size  = MediaQuery.of(context).size; // screen metrics

  return Container(
    width: size.width * 0.9,
    color: theme.colorScheme.surface,
    child: Text('Adapts to theme & screen',
      style: theme.textTheme.titleMedium),
  );
}

This is Flutter's answer to dependency lookup: instead of threading the theme through every constructor, you put it once near the top (inside a MaterialApp, which you'll see in module 10) and any descendant reads it via context. The mechanism underneath is the InheritedWidget — a widget that exposes data efficiently to everything below it, and rebuilds only the widgets that actually read it when the data changes. You rarely write one by hand early on, but Theme, MediaQuery, and most state-management libraries are built on it.

build is for describing, not for doing. So the side-effecting work — subscribing to a stream, creating an animation controller, starting a timer — belongs in the State lifecycle methods, which mirror the native ones you already use.

The pairing that matters most is initState/dispose. Anything you create in the first you must tear down in the second, or you leak. Text fields make this concrete: they use a TextEditingController, which you own.

class _SearchState extends State<Search> {
  late final TextEditingController _controller;

  @override
  void initState() {
    super.initState();
    _controller = TextEditingController();
  }

  @override
  void dispose() {
    _controller.dispose();   // or you leak the controller
    super.dispose();
  }

  @override
  Widget build(BuildContext context) =>
      TextField(controller: _controller);
}

Note late final: the controller is set exactly once, in initState, not at the declaration — because you want it created when the State mounts, not before. Also note that both initState and dispose call super; forgetting that is a common early slip.

@override
void dispose() {
  _sub.cancel();      // stop listening when we leave
  super.dispose();
}

You could build a list by dumping every item into a Column inside a SingleChildScrollView. For ten items, fine. For ten thousand, you'd build ten thousand widgets up front and run out of memory. The native answer is cell recycling; Flutter's is lazy building.

ListView.builder takes an item count and a builder callback, and only calls the builder for items near the viewport — building them as they scroll into view and letting off-screen ones go. No delegates, no reuse identifiers, no dequeue. Just a function from index to widget.

ListView.builder(
  itemCount: messages.length,
  itemBuilder: (BuildContext context, int i) {
    final m = messages[i];
    return ListTile(
      leading: CircleAvatar(child: Text(m.initials)),
      title: Text(m.sender),
      subtitle: Text(m.preview),
      onTap: () => _open(m),
    );
  },
)

Compare the mental overhead. A UITableView needs a data source, cell registration, and careful reuse to avoid showing stale content in recycled cells. Here the builder is a pure function of the index — there's no recycled cell to accidentally show the wrong data, because each visible item is described fresh. The performance is equivalent; the footguns are gone.

A screen in Flutter is called a route, and routes live on a stack managed by the Navigator. It's exactly the push/pop model you know from UINavigationController and the Android back stack. Pushing a route slides a new screen on top; popping removes it and reveals the one beneath.

// go to a detail screen, passing data in via its constructor
final picked = await Navigator.push<Color>(
  context,
  MaterialPageRoute(
    builder: (context) => ColorPickerScreen(title: 'Pick'),
  ),
);

// back on the first screen, `picked` is whatever the second popped with
if (picked != null) setState(() => _color = picked);

Navigator.pop(context, Colors.teal);  // pops & returns teal

Two things stand out for a native developer. First, you pass data into a screen the obvious way — as constructor arguments to its widget — not through a segue or an Intent extra. Second, getting a result back is just awaiting the push: the future completes when the pushed route pops, with whatever value it popped. No delegate protocol, no onActivityResult. It reads like a function call that happens to draw a screen.

Most screens show something that isn't ready yet: a profile being fetched, a price ticking over a socket. Because your UI is a function of your data, the question becomes "what's the description while the data is still loading, or if it failed?" Flutter answers with builder widgets that hand you the current async status and let you return a widget for each case.

FutureBuilder<User>(
  future: _fetchUser(id),          // a Future<User>
  builder: (context, snapshot) {
    if (snapshot.connectionState != ConnectionState.done) {
      return const CircularProgressIndicator();  // loading
    }
    if (snapshot.hasError) {
      return Text('Failed: ${snapshot.error}'); // error
    }
    return Text(snapshot.data!.name);              // success
  },
)

The snapshot is a little bundle describing "where is this async operation right now" — still waiting, done with data, or done with an error. You branch on it and return the appropriate widget. There's no manual "hide the spinner, show the content" toggling of view visibility; you describe all three states declaratively and Flutter shows whichever matches.

For a sequence of values over time — a websocket, sensor readings, a database query that re-emits on change — use StreamBuilder with a Stream. Same shape; it just rebuilds each time a new value arrives.

StreamBuilder<int>(
  stream: _temperatures,
  builder: (context, snap) {
    if (snap.hasError) return const Text('—');
    if (!snap.hasData)  return const CircularProgressIndicator();
    return Text('${snap.data}°C');
  },
)

setState is perfect for state a single widget owns. But real apps have state many screens care about: the signed-in user, the cart, a theme choice. Passing it down by constructor through ten layers ("prop drilling") gets miserable fast. You need a way to lift state up and let interested widgets read it from anywhere below.

The techniques form a ladder, and every rung is the same core idea — put the state above the widgets that need it, and expose it through the tree:

Don't reach for a big library on day one. Build a screen or two with setState and lifted state; feel where it hurts. The pain — "I'm passing this callback through five widgets that don't care about it" — is what the packages remove, and you'll appreciate them far more once you've felt the problem they solve. When you do choose one, Riverpod is the common modern default; Bloc suits teams that want a strict, event-driven structure.

Flutter draws every pixel itself, so it ships two complete design systems as widget libraries: Material (Google's, the default, works on both platforms) and Cupertino (Apple's look). Most teams build in Material for both platforms; you reach for Cupertino widgets when you specifically want iOS-native styling.

Two widgets anchor almost every Material app. MaterialApp sits at the very top and provides theming, navigation, and localisation to everything below. Scaffold gives a single screen its standard furniture: an app bar, a body, a floating action button, a drawer, bottom navigation.

MaterialApp(
  theme: ThemeData(
    colorScheme: ColorScheme.fromSeed(
      seedColor: Colors.indigo,   // whole palette from one colour
    ),
    useMaterial3: true,
  ),
  home: Scaffold(
    appBar: AppBar(title: const Text('Inbox')),
    body: const MessageList(),
    floatingActionButton: FloatingActionButton(
      onPressed: _compose,
      child: const Icon(Icons.edit),
    ),
  ),
)

Note ColorScheme.fromSeed: give it one seed colour and Material 3 derives a full, accessible light-and-dark palette. Because every Material widget reads its colours from the theme via Theme.of(context) (module 4), changing that seed restyles the entire app — buttons, app bars, switches, all of it — from a single line. That's the theming payoff of "everything reads from an ancestor".

Recall §3: when rebuilding, Flutter matches each new widget to an existing element by position and type, and preserves the element's State when they match. That heuristic is right almost always — and wrong in one specific, memorable case: reordering or removing items in a list of stateful widgets of the same type.

Picture three TodoTiles, each stateful (say each holds a half-typed edit). You delete the first. The list now has two widgets; Flutter matches them by position to the first two elements — so the second tile's in-progress edit stays attached to the first position. The widgets moved but the state didn't follow, because position was the only thing Flutter had to match on. Visually: the wrong row keeps the wrong state.

Column(children: [
  TodoTile(todo: a),
  TodoTile(todo: b),
])
// reorder → State stays put,
// data swaps under it. Bug.

Column(children: [
  TodoTile(key: ValueKey(a.id), todo: a),
  TodoTile(key: ValueKey(b.id), todo: b),
])
// reorder → State follows its key.
// Correct.

A Key gives a widget a stable identity independent of position. With ValueKey(item.id), Flutter matches new widgets to old elements by key first, so each tile's state travels with its data no matter how the list is reordered. The rule of thumb: add keys when you have a list of stateful widgets of the same type that can reorder, insert, or delete. Static layouts almost never need them.

Flutter's headline feature for day-to-day work is hot reload. Save a file and your running app updates in well under a second, keeping its current state — you stay on the same screen, with the same data, and just see your change. After years of rebuild-and-relaunch cycles on native, this alone changes how you work: you tweak a padding, glance, tweak again, in a tight loop.

When something's off, Flutter DevTools gives you a live widget inspector (tap a pixel, see its widget tree), a layout explorer that visualises those constraints from module 3, plus performance, memory, and network views. The inspector especially is worth opening early — seeing your three trees rendered live cements everything in Part 1.

Testing comes in three tiers, and the middle one is Flutter's sweet spot:

testWidgets('tapping increments the counter', (tester) async {
  await tester.pumpWidget(const MyApp());
  expect(find.text('0'), findsOneWidget);

  await tester.tap(find.byIcon(Icons.add));
  await tester.pump();               // let the rebuild happen

  expect(find.text('1'), findsOneWidget);
});

Widget tests run in seconds with no emulator, and because your whole UI is a function of state, they're unusually reliable — you pump a widget, simulate taps, and assert on what's rendered. Coming from native UI testing's flakiness, this is a genuine upgrade.

The honest difficulty map

Now that the vocabulary means something, here's what's still ahead — ranked so you can tell a genuinely hard topic from a gap in your understanding.

Where to go next

One closing thought, and it's the most useful sentence here. Nearly every Flutter surprise — the stale label, the overflow stripe, the form that resets, the wrong row's state — comes back to one of the ideas in Part 1: UI is a function of data, and there are three trees. When something baffles you, don't reach for a workaround. Ask which of those two ideas you've bumped into. That reframe is what turns the first fortnight from a fight into a conversation.