Home › Introduction to Flutter UI › DevTools

🔍 DevTools — Your X-Ray Vision for Flutter Apps

⏱️ 20-25 minutes 📊 Beginner — Learn debugging tools! 🛠️ No projects — Hands-on tool exploration 🏷️ DevTools, Inspector, Debugging, Properties

🧒 What Are DevTools? (The X-Ray Analogy!)

🩻

Imagine Having X-Ray Vision for Your App...

When you look at your app, you see colored squares with letters. But underneath, there's a hidden world — the widget tree, properties, constraints, and layout calculations that Flutter uses to draw every pixel on screen.

DevTools gives you X-ray vision! It lets you:

  • 🔍 See through your app to the widget tree underneath
  • 🖱️ Click on any widget to see all its properties
  • 🔧 Change properties live and see the results instantly
  • 🐛 Find and fix bugs that would be invisible otherwise
💪
Why this matters: Professional developers spend up to 40% of their time debugging. Mastering DevTools early will save you hundreds of hours of frustration. Think of it as learning to use a map before going on a long journey!
🦸

DevTools Has Two Superpowers

🌳

1. Widget Inspector

Shows your entire widget tree like a family tree. Click any widget to see where it lives, what contains it, and what it contains. It's like Google Maps for your app's structure!

✏️

2. Property Editor

When you select a widget, this shows every property it has — width, height, color, padding, you name it. You can change values live and see the results instantly!

🐛

Bonus: Bug Finder!

DevTools helps you spot the dreaded "unbounded constraints" error — the #1 mistake Flutter beginners make. You'll learn exactly what it means and how to fix it.

🔗

How DevTools Talks to Your App

DevTools doesn't live inside your app — it's a separate website that connects to your running app through a special link. Think of it like a video call between your app and the DevTools website:

📱 Your App Running in Chrome
← debug link →
🖥️ DevTools Opens in browser

When you change a property in DevTools, it writes directly to your code file on your computer. Then when you hot reload, your app updates instantly. It's like having a remote control for your code!

1 Launch DevTools — Open Your X-Ray Machine

First, let's get DevTools running. You need your app to be already running in debug mode for this to work.

Step 1.1 Make Sure Your App is Running

If your Birdle app isn't running, start it now:

Terminal — Start Your App
~/birdle $ flutter run -d chrome
Launching lib/main.dart on Chrome in debug mode...
✓ Built build/web/...
Debug service listening on ws://127.0.0.1:...
Serving DevTools at http://127.0.0.1:9101
⚠️
Important! Keep this terminal window open and running. Your app needs to stay alive for DevTools to connect to it. Don't close it or press q!

Step 1.2 Start the DevTools Server

Open a second terminal window (yes, you need two terminals — one for the app, one for DevTools). In VS Code, you can click the + button in the terminal panel to open a new terminal.

In the new terminal, run this command:

New Terminal — Launch DevTools
~ $ dart devtools
Serving DevTools at http://127.0.0.1:9100

✓ DevTools server is running.

Your browser should automatically open a new tab with the DevTools interface. If it doesn't, copy the URL from the terminal and paste it into your browser.

💡
What is dart devtools? This command starts a small web server on your computer that hosts the DevTools website. It's like turning on a local website that only you can access. The URL usually starts with http://127.0.0.1 (which means "this computer").

Step 1.3 Connect DevTools to Your Running App

Now you need to link DevTools to your app. Here's how:

  1. Look at the first terminal (where your app is running)
  2. Find the line that says: Serving DevTools at http://127.0.0.1:9101
  3. Copy that URL (it might be a different port number like 9102 or 9103)
  4. Go to the DevTools browser tab
  5. You'll see a connection bar at the top asking for a URL
  6. Paste the URL and click "Connect"
✅
If connected successfully: You should see your app's name appear in DevTools, and the Widget Inspector will show your widget tree. If it doesn't connect, make sure your app is still running and you copied the correct URL.

2 The Widget Inspector — See Through Your App

The Widget Inspector is like Google Maps for your widget tree. It shows every widget, how they're connected, and lets you click on anything to inspect it.

Step 2.1 Explore Your Widget Tree

In DevTools, click on the "Widget Inspector" tab (it's usually the first tab). You'll see a tree structure that looks something like this:

🌳 MaterialApp The root widget
│
🏠 Scaffold App structure
│
📦 Center Centers children
│
↕️ Column Stacks 5 children
├── ── ── ── ──┤
↔️ Row
│
🧩 Tile ×5
↔️ Row
│
🧩 Tile ×5
... 3 more Rows ...
🖱️
Try this now: Click on any widget in the DevTools tree. The widget will highlight on your running app, showing you exactly which part of the screen it controls. Click on a Tile — you'll see the exact square light up!

Step 2.2 Understanding the Tree in DevTools vs Your Code

Here's how the code you wrote maps to what you see in DevTools:

📝 Your Code (main.dart)

MaterialApp(
    home: Scaffold(
        body: Center(
            child: Column(
                children: [
                    Row(children: [
                        Tile('B', HitType.hit),
                        Tile('I', HitType.partial),
                        ...
                    ]),
                    Row(children: [...五个 Tiles...]),
                    ...
                ],
            ),
        ),
    ),
)
→ maps to →

🔍 DevTools Widget Tree

📦 MaterialApp
└─ 🏠 Scaffold
└─ 📦 Center
└─ ↕️ Column
├─ ↔️ Row
│ ├─ 🧩 Tile "B"
│ ├─ 🧩 Tile "I"
│ └─ ...
├─ ↔️ Row
└─ ...

See the pattern? Every widget in your code becomes a node in the DevTools tree. The nesting (indentation) in your code becomes the tree branches. If you can read your code, you can read the Widget Inspector!

Step 2.3 Select Widgets on Screen

There's an even easier way to inspect widgets — click them directly on your app!

  1. In DevTools, find and click the "Select Widget Mode" button (it looks like a cursor icon 🖱️)
  2. Now go to your running app in Chrome
  3. Hover over any Tile — it will highlight with a blue border
  4. Click on a Tile — DevTools will automatically select that widget in the tree!
🎯
This is the fastest way to debug! Instead of searching through the tree, just click what you want to inspect. It's like clicking on a house in Google Maps to see its address — instant and intuitive.

3 Debugging Layout Issues — The Dreaded "Unbounded Constraints"

This is the #1 most common error Flutter beginners face. Let's understand what it means and how to fix it forever.

Step 3.1 What Are "Constraints" in Flutter?

In Flutter, every widget gives constraints to its children. It's like a parent telling their child: "You can be this wide and this tall — no bigger, no smaller."

✅ Normal Constraints

Parent says: "Be exactly 60×60 pixels"

60×60

Child is happy — it knows exactly what size to be!

❌ Unbounded Constraints

Parent says: "Be as big as you want!"

∞ × ∞

Child panics — "How big is infinity?! I can't be infinite!" 💥

Step 3.2 When Does This Happen?

The most common situations that cause unbounded constraints:

🔴 Scenario 1: Column inside a ListView (vertical)

A vertically scrolling ListView gives its children infinite height (because it can scroll forever). If you put a Column inside, the Column tries to be infinitely tall and crashes.

// ❌ THIS WILL CRASH!
ListView(
    children: [
        Column(  // ← Column gets infinite height!
            children: [Text('Hello'), Text('World')],
        ),
    ],
)

🔴 Scenario 2: Row inside a ListView (horizontal)

A horizontally scrolling ListView gives infinite width. A Row inside will try to be infinitely wide and crash.

🔴 Scenario 3: Flexible/Expanded without a flex parent

Using Expanded or Flexible outside of a Row, Column, or Flex widget causes unbounded constraints because there's no flex container to negotiate sizes.

🔑
The golden rule: Scrollable widgets (ListView, GridView, SingleChildScrollView) give infinite constraints in their scrolling direction. Never put a Row/Column directly inside a scrollable in the same direction without wrapping it properly.

Step 3.3 How DevTools Helps You Find These Errors

When your app crashes with an unbounded constraints error, DevTools shows you:

Error Output in Terminal
════════ Exception caught by rendering library ════════
RenderFlex children have non-zero flex but incoming
height constraints are unbounded.

The affected RenderFlex is:
  RenderFlex#ab12c relayoutBoundary=up2
  creator: Column ← Padding ← Center ← Scaffold ← ...
  parentData: <none>
  constraints: BoxConstraints(0.0<=w<=400, 0.0<=h<=Infinity)

How to read this error:

  1. Look for constraints: BoxConstraints(... h<=Infinity) — this tells you which direction is unbounded (height in this case)
  2. Look at the creator line — it shows you exactly which widget is causing the problem
  3. The widget path (Column ← Padding ← Center ← ...) shows you where in the tree the problem is

4 The Property Editor — Change Things Live!

This is the coolest feature of DevTools. You can change widget properties and see the results instantly — without even touching your code!

Step 4.1 Find the Property Editor

When you select any widget in the Widget Inspector, the Property Editor appears on the right side (or bottom, depending on your screen size). It shows every property of that widget.

For example, if you select a Container inside a Tile, you'll see:

Container StatelessWidget
width 60.0
height 60.0
decoration BoxDecoration
↳ border Border.all(...)
↳ color Colors.green
child Center

Step 4.2 Experiment! Change a Property Live

Here's a fun experiment to try right now:

  1. In DevTools, use Select Widget Mode and click on any Tile in your app
  2. In the Property Editor, find the width property (showing 60.0)
  3. Double-click on the number 60.0
  4. Change it to 100.0
  5. Press Enter

Now hot reload your app (press r in the terminal). Boom! Your tile is now 100 pixels wide instead of 60. And here's the magic — DevTools actually edited your main.dart file for you!

✨
This is huge! You can experiment with different sizes, colors, padding values, and more — all without typing a single line of code. When you find what looks good, DevTools has already saved it to your file. This is called "rapid iteration" and it's how professional designers fine-tune UIs.

Step 4.3 Things You Can Edit in the Property Editor

Here's a list of properties you should try changing on your Tile widget:

📏 Size

Change width and height from 60 to 80 or 40. See how the grid spacing changes.

🎨 Colors

Change Colors.green to Colors.blue, Colors.orange, or Colors.purple.

📐 Border

Change the border color from Colors.grey.shade300 to Colors.black for thicker-looking borders.

📝 Text Style

Select the Text widget inside Tile and change titleLarge to headlineMedium for bigger text.

📝 What You Learned Today

You just unlocked a superpower that most beginners don't discover until months into their journey!

✅

Launched DevTools

Used dart devtools to start the DevTools server and connected it to your running Flutter app.

✅

Explored the Widget Tree

Used the Widget Inspector to visualize your entire widget tree, from MaterialApp down to every Tile.

✅

Understood Unbounded Constraints

Learned what causes the #1 Flutter error — when widgets get infinite constraints from scrollable parents.

✅

Used the Property Editor

Changed widget properties live, saw instant updates, and learned that DevTools edits your source files directly.

🧠 Test Yourself!

Let's check your understanding of DevTools:

Q1 What is a common cause of "unbounded constraints" errors in Flutter?

Q2 What can you do with the Widget Inspector in Flutter DevTools?

🖐️ Hands-On Exercise 1: Inspector Scavenger Hunt

Let's practice using the Widget Inspector with a fun scavenger hunt!

Exercise 1 Beginner

Objective: Find These Widgets in Your Tree

🔍 Find and click on each of these in the Widget Inspector:

  1. Find the MaterialApp — it should be at the very top of the tree
  2. Find a Scaffold — what's its parent widget?
  3. Find the Column that holds all the rows — how many direct children does it have?
  4. Find a Tile widget — click on it and look at the Property Editor
  5. Find the Container inside a Tile — what's its width and height?
  6. Use Select Widget Mode to click on a Tile directly on your app screen
💡
Hint: If you get lost, use the search bar at the top of the Widget Inspector to search for widget names like "Tile" or "Container".

🖐️ Hands-On Exercise 2: Live Property Editing

Now let's practice changing properties and seeing the results!

Exercise 2 Beginner

Objective: Make These Changes Using the Property Editor

✏️ For each change, use the Property Editor (not your code editor!):

  1. Change a Tile's width from 60 to 80 — hot reload and see the bigger square
  2. Change the hit color from green to blue (Colors.blue)
  3. Change a Tile's border color from Colors.grey.shade300 to Colors.black
  4. Find the AppBar title Text widget and change its text from "Birdle 🐦" to "My Game 🎮"
  5. Change the spacing (SizedBox height) between rows from 4 to 10

🎯 After this exercise:

Your app should look different — bigger tiles, different colors, and more spacing. You changed all of this without writing a single line of code manually!

⚠️
Remember: The Property Editor permanently changes your source code. If you want to go back to the original, you'll need to undo the changes in your code editor (Ctrl+Z / Cmd+Z). This is great for experimenting, but be aware that your files are being edited!

🚀 What's Next?

Now you have X-ray vision for your Flutter apps! In the next lesson, you'll learn:

  • Handle User Input — Make your app interactive with buttons, text fields, and gestures
  • Let users actually type their guesses in the Birdle game
  • Respond to taps, typing, and form submissions
Next Lesson: Handle User Input →
🎉

Lesson Complete!

You now know how to use Flutter DevTools — one of the most powerful tools in a Flutter developer's arsenal. You can now debug your apps like a professional!

Click the button above to track your progress!