How to Use ListView.builder for Dynamic List Display in Flutter

Imagine you have a very long list of items—think thousands of user comments, product listings, or chat messages. If you tried to display this with a basic ListView(children: [...]), Flutter would attempt to build every single widget for every single item right when the screen first loads.

ListView.builder solves this by being lazy. It doesn't build all items at once. Instead, it only builds the widgets that are actually visible on the screen (plus a small buffer). As you scroll, it recycles those widgets, updating them with new data for the next items. It's like having a small, efficient assembly line that only prepares the next item right before you need to see it.

This "laziness" is what makes it perfect for dynamic lists—lists where the data can change, be very long, or come from a source like an API. The common misconception is that ListView.builder is just a fancy way to write a static list. That's backwards. Its real power shines precisely when your list is not static.

Think of a static list like a printed menu—it's fixed once it's on the table. A dynamic list is more like a live scoreboard: numbers change, items get added or removed, and the display updates automatically.

In Flutter, a dynamic list isn't magic—it's state-driven. The itemBuilder doesn't care if your data came from an API, a database, or a user action. It only cares about the current state of your data list at the moment it's called.

Here's the intuition: When your list's data changes, you update the underlying list variable (e.g., myItems.add(newItem)) and then call setState().

That single setState tells Flutter: "Something in this widget's state changed—re-run build." During that rebuild, ListView.builder asks your itemBuilder for widgets again, but now your data list has the new items.

class MyListWidget extends StatefulWidget {
  @override
  _MyListWidgetState createState() => _MyListWidgetState();
}

class _MyListWidgetState extends State<MyListWidget> {
  List<String> items = ['Apple', 'Banana'];

  void _addItem() {
    setState(() {
      items.add('Cherry'); // 1. Update the data source
      // 2. No manual ListView refresh needed!
    });
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        ElevatedButton(
          onPressed: _addItem, 
          child: Text('Add')
        ),
        ListView.builder(
          itemCount: items.length, // Uses current length
          itemBuilder: (context, index) {
            return ListTile(
              title: Text(items[index])
            );
          },
        ),
      ],
    );
  }
}

On a phone, resources are tight: memory is limited, the CPU is slower, and the battery is precious. A list that scrolls smoothly on a high-end laptop can stutter or crash on a budget Android device if you're not careful.

Here is a common misconception: "Using ListView.builder automatically guarantees good performance everywhere."

That's not true. ListView.builder solves the number of widgets problem by building only what's visible. But it doesn't magically make each individual item cheap to build or render.

The real performance culprits on mobile are often hidden inside your itemBuilder.

ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) {
    // ❌ Expensive: parsing a date string on every build
    final formattedDate = DateFormat.yMMMd().format(items[index].timestamp);
    
    // ❌ Complex: multiple nested containers and text styles
    return Container(
      padding: EdgeInsets.all(8),
      child: Column(
        children: [
          Text(items[index].title, style: Theme.of(context).textTheme.headline6),
          SizedBox(height: 4),
          Text(formattedDate),
          // ... more widgets
        ],
      ),
    );
  },
);

Technical Reasoning: On low-end devices, the GPU and main thread have less headroom. Each frame has a tight budget (~16ms for 60fps). If your itemBuilder takes 5ms per item and you have 5 visible items, that's 25ms just for building—leaving little time for layout, paint, and rasterization. Add a complex layout or image decode, and you'll drop frames.

Real-world screens are rarely just a list. Often, you have a Header, some Introductory Text, a Form, and then a list of items. Naturally, you want to scroll all of this together in one smooth motion.

Your instinct might be to wrap everything in a SingleChildScrollView and drop your ListView.builder inside it.

To fix this, we need to tell the ListView to stop trying to fill the whole screen and instead just wrap its content. We do this with two properties:

SingleChildScrollView(
  child: Column(
    children: [
      Text('Page Title'),
      Text('Intro text...'),
      
      ListView.builder(
        shrinkWrap: true, // 1. Fit to content
        physics: NeverScrollableScrollPhysics(), // 2. Disable internal scroll
        itemCount: items.length,
        itemBuilder: (context, index) {
          return ListTile(
            title: Text(items[index]),
          );
        },
      ),
    ],
  ),
);

The most common misconception about ListView.builder is that it loads all items at once—just like a regular ListView(children: [...]), but with slightly better syntax.

That is backwards.

Think of ListView.builder not as a list of items, but as a factory on demand. You give it two things:

The factory doesn't start printing all pages immediately. It only prints the page you're currently looking at. When you scroll to the next page, it prints that one—reusing the same machinery. It never prints pages you haven't reached and won't reach.

So the correct intuition is: ListView.builder builds widgets only when they are about to scroll into view, not all at once. The itemBuilder function is called repeatedly, on-demand, for each index as it becomes visible. Your list's total length (itemCount) is just a boundary; it doesn't trigger building all those widgets upfront.

ListView.builder(
  itemCount: 1000, // Pretend we have 1000 items
  itemBuilder: (context, index) {
    print('Building item $index'); // Watch your console as you scroll
    return ListTile(title: Text('Item $index'));
  },
)

When you run this, you'll see prints only for the first few items (e.g., 0–8). As you scroll down, new prints appear for the next indices. Items that scrolled off-screen may be reused for new indices, but you'll never see prints for all 1000 items at once.

Many developers assume that ListView.builder is the "magic bullet" for performance in all scenarios. While it is incredibly powerful, it is not always the fastest option.

Its speed advantage comes from lazy loading. But if you accidentally disable that laziness, you might end up with code that is slower and more complex than a simple static list.

As you can see, the standard list is nearly instant because it only builds what fits on the screen. The shrinkWrap version has to do a lot of extra work upfront just to know how tall to be.

SingleChildScrollView(
  child: Column(
    children: [
      Text('Header'),
      // ⚠️ DANGER: Forces all items to build!
      ListView.builder(
        shrinkWrap: true, // Causes the freeze
        physics: NeverScrollableScrollPhysics(),
        itemCount: 1000,
        itemBuilder: (context, index) {
          return ListTile(title: Text('Item $index'));
        },
      ),
    ],
  ),
);

Technical Reasoning: Under the hood, ListView.builder uses a SliverChildBuilderDelegate. When shrinkWrap is true, the layout engine asks the delegate for the total extent (height). To calculate this, the delegate must build every single child to measure it. This turns your lazy list into an eager one, causing high memory usage and initial lag.

Let's get our hands dirty. Setting up a ListView.builder is deceptively simple, but there is one parameter you absolutely cannot ignore.

Intuition: The Factory Assembly Line

Think of ListView.builder as a factory assembly line. To run this factory, you need two things:

As you can see, the "Safe" factory stops exactly when it hits the limit. The "Unsafe" factory keeps going, and eventually, it runs into data it doesn't have (since your data list isn't infinite), causing a RangeError or a crash.

ListView.builder(
  itemCount: myList.length, // ⚠️ REQUIRED: The Safety Boundary
  itemBuilder: (context, index) {
    return ListTile(
      title: Text(myList[index]),
    );
  },
)

Let's demystify the magic. The most common misconception about ListView.builder is that it constructs all widgets up front.

That is the exact opposite of how it works.

Technical Reasoning: Internally, ListView.builder uses a SliverChildBuilderDelegate. During the first layout pass, Flutter's rendering pipeline determines which item indices fit within the viewport's visible area. It then invokes your itemBuilder only for those indices.

ListView.builder(
  itemCount: 1000, // The total script length
  itemBuilder: (context, index) {
    // This ONLY runs for visible items!
    print('Building widget for index $index');
    return ListTile(title: Text('Item $index'));
  },
)

The itemCount is essential because it defines the finite scroll extent. Without it, the builder would have no stopping point and would keep requesting new indices forever.

Let's get practical. The most common stumbling block for beginners is the idea that ListView.builder is a separate entity that needs to be "told" to update.

Think of your widget's build method as a live camera feed. The camera (the UI) doesn't store the picture; it shows whatever is currently in front of the lens. When you change the scene (your data), the camera feed updates automatically. You don't need to replace the camera; you just change the scene.

Here is the exact code pattern you should use. It looks simple, but it relies on the "Reactive Mirror" principle.

class MyListScreen extends StatefulWidget {
  @override
  _MyListScreenState createState() => _MyListScreenState();
}

class _MyListScreenState extends State<MyListScreen> {
  // 1. The Data Source lives in the State
  List<String> _items = ['Apple', 'Banana'];

  void _addItem() {
    // 2. Update the data AND trigger rebuild
    setState(() {
      _items.add('Cherry'); 
      // No need to touch ListView!
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: ListView.builder(
        itemCount: _items.length, // Reads current length
        itemBuilder: (context, index) {
          // Reads current data
          return ListTile(title: Text(_items[index]));
        },
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _addItem,
        child: Icon(Icons.add),
      ),
    );
  }
}

Technical Reasoning: When setState is called, Flutter marks the widget as "dirty" and schedules a rebuild. During that rebuild:

1. The Data List already contains the new item because we mutated it inside setState.
2. The itemCount is re-evaluated and returns the new length.
3. The Element Tree sees the ListView is the same type with the same key, so it updates its internal logic to account for the new index.
4. The itemBuilder is called for the new index, pulling the fresh data from the list.

Think of lazy loading like a smart librarian. Instead of pulling every book off the shelf and stacking them on your table (which would collapse the table), the librarian only hands you the next book right before you need it, and takes back the one you just finished. The table never holds more than a few books at once—saving massive space.

ListView.builder does exactly this for your widgets: it only keeps the visible items (plus a small buffer) in memory. That's the memory savings. But here's the catch: if each of those few "books" is a giant, heavily illustrated encyclopedia, the librarian still struggles to hand them to you quickly.

Technical Reasoning: Smoothness depends on per-frame work. Even if you only have 6 items on screen, if each one takes 3ms to build and layout, that's 18ms just for the build phase. You've already exceeded the ~16ms budget needed for 60fps before the GPU even starts painting.

ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) {
    // ❌ Expensive: parsing a date string on every build
    final formattedDate = DateFormat.yMMMd().format(items[index].timestamp);
    
    // ❌ Complex: multiple nested containers and text styles
    return Container(
      padding: EdgeInsets.all(8),
      child: Column(
        children: [
          Text(items[index].title, style: Theme.of(context).textTheme.headline6),
          SizedBox(height: 4),
          Text(formattedDate),
          // ... more widgets
        ],
      ),
    );
  },
);

Diagnosing the Real Bottleneck: Don't guess—measure. Use Flutter DevTools' Performance tab. If your itemBuilder appears repeatedly in the "Build" section with high cost, that's your culprit.

Let's move from theory to practice. The most common stumbling block when combining ListView.builder with network requests is timing.

Intuition: The Restaurant Analogy

Think of an API call like ordering food at a restaurant.

The misconception is that you need to call setState repeatedly during the wait—perhaps once to start the spinner, and again for every tiny bit of data that arrives.

Technical Reasoning: When you call setState, Flutter schedules a rebuild. If you call it repeatedly inside an async loop (e.g., for every chunk of data), you force the UI to repaint constantly while the data is incomplete.

void _fetchData() async {
  // 1. Set loading state FIRST (Optional, if not already set)
  setState(() {
    _isLoading = true;
  });

  try {
    // 2. Wait for the Future to complete
    final response = await http.get(uri);
    final newItems = parseResponse(response);

    // 3. Update state ONCE with the final data
    setState(() {
      _items = newItems; // Data is ready!
      _isLoading = false;
    });
  } catch (e) {
    setState(() {
      _error = e.toString();
      _isLoading = false;
    });
  }
}

By accumulating the data first and then calling setState once, you ensure the ListView.builder renders the complete list in a single, efficient pass.

We've covered a lot of ground, but at its heart, ListView.builder is about respecting your device's limits.

The misconception is that ListView.builder is just a more complicated way to write a list. That's backwards. The simplicity of the standard ListView is precisely its limitation: it builds every child widget immediately.

ListView(
  children: items.map((item) => 
    ListTile(title: Text(item))
  ).toList(), // Builds ALL at once!
)

ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) => 
    ListTile(title: Text(items[index]))
)

Technical Reasoning: When you use .toList(), Flutter constructs all those widgets during the initial build. Even if only 6 are visible, the other 94 are built, laid out, and kept in memory. This defeats the purpose of lazy rendering and can cause your app to freeze.

Hello again! I know you have questions. It's natural to wonder, "Is this really necessary?" or "What happens if I get this wrong?". Let's tackle the most common questions I get from my students, using visuals to make the answers stick.

ListView.builder(
  itemBuilder: (context, index) {
    return Text('Item $index');
  },
  itemCount: 100,
)

final users = [User('Alice'), User('Bob')];

ListView.builder(
  itemCount: users.length,
  itemBuilder: (context, index) {
    // Access the custom object
    final user = users[index]; 
    
    return Text(user.name); // Use its properties
  },
)