Flutter ListView.builder: The Complete Beginner’s Guide (2026)

Every Flutter app with more than a few items needs a list. The question is which list widget to use — and getting this wrong on a large dataset means your app builds hundreds of widgets at once, eating memory and causing jank.

Flutter’s answer is ListView.builder: a lazy-loading list that only builds the items currently visible on screen. It is the official recommendation for any long, dynamic, or API-driven list, and once you understand its two required parameters, almost every list in your app becomes easy to build.

This guide starts with the minimal example and builds up to real-world patterns: lists of objects, custom card widgets, dividers, pull-to-refresh, loading skeletons, basic pagination, and horizontal lists. Every common mistake has a working fix.

1. ListView vs ListView.builder

Flutter has two primary list constructors. Understanding the difference is the first thing to get right before writing any list code:

// The lazy-loading mental model:
//
// ListView builds ALL items at once:
//   Item 0, Item 1, Item 2 ... Item 999 ← all 1000 widgets created immediately
//
// ListView.builder builds ONLY visible items:
//   Screen shows items 0–7
//   ↓ user scrolls ↓
//   Item 0 is recycled, Item 8 is built
//   Only ~8 widgets exist in memory at any time regardless of list size

2. The Minimal Example

ListView.builder needs exactly two things: itemCount (how many items total) and itemBuilder (what to render for each index). The builder receives two arguments — BuildContext context and int index — where index starts at 0 and goes up to itemCount - 1:

import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: SimpleListPage()));
}

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Simple List')),
      body: ListView.builder(
        itemCount: 20,                              // how many items to build
        itemBuilder: (context, index) {             // called once per visible item
          return ListTile(
            leading: CircleAvatar(child: Text('$index')),
            title: Text('Item $index'),
            subtitle: Text('Index starts at 0, ends at ${20 - 1}'),
          );
        },
      ),
    );
  }
}

3. Real Example with a Data List

Most apps render ListView.builder from a real List. The key is passing myList.length as itemCount and accessing myList[index] inside itemBuilder. Here is a complete example with a list of maps:

import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: FruitListPage()));
}

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

  // The data source — in a real app this comes from an API or database
  static const List<Map<String, dynamic>> fruits = [
    {'name': 'Apple',      'emoji': '🍎', 'color': Color(0xFFE53935)},
    {'name': 'Banana',     'emoji': '🍌', 'color': Color(0xFFFDD835)},
    {'name': 'Cherry',     'emoji': '🍒', 'color': Color(0xFFD81B60)},
    {'name': 'Grape',      'emoji': '🍇', 'color': Color(0xFF8E24AA)},
    {'name': 'Mango',      'emoji': '🥭', 'color': Color(0xFFFB8C00)},
    {'name': 'Kiwi',       'emoji': '🥝', 'color': Color(0xFF43A047)},
    {'name': 'Lemon',      'emoji': '🍋', 'color': Color(0xFFF9A825)},
    {'name': 'Watermelon', 'emoji': '🍉', 'color': Color(0xFF00897B)},
    {'name': 'Peach',      'emoji': '🍑', 'color': Color(0xFFFF7043)},
    {'name': 'Blueberry',  'emoji': '🫐', 'color': Color(0xFF1E88E5)},
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Fruits (${fruits.length})'),
      ),
      body: ListView.builder(
        padding: const EdgeInsets.symmetric(vertical: 8),
        itemCount: fruits.length,         // ← always use list.length
        itemBuilder: (context, index) {
          final fruit = fruits[index];    // ← access the item at this index
          return Card(
            margin: const EdgeInsets.symmetric(horizontal: 12, vertical: 4),
            child: ListTile(
              leading: CircleAvatar(
                backgroundColor: fruit['color'] as Color,
                child: Text(
                  fruit['emoji'] as String,
                  style: const TextStyle(fontSize: 20),
                ),
              ),
              title: Text(
                fruit['name'] as String,
                style: const TextStyle(fontWeight: FontWeight.w600),
              ),
              subtitle: Text('Item ${index + 1} of ${fruits.length}'),
              trailing: const Icon(Icons.arrow_forward_ios, size: 14),
              onTap: () {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(
                    content: Text('Tapped: ${fruit['name']}'),
                    duration: const Duration(seconds: 1),
                  ),
                );
              },
            ),
          );
        },
      ),
    );
  }
}

4. Custom Card Item Widget

As list items get more complex, keeping all the UI inside itemBuilder makes it hard to read and maintain. Extract each item into its own widget. This keeps itemBuilder to a single line and lets Flutter optimise rebuilds more precisely:

import 'package:flutter/material.dart';

// 1. Define a typed data model — better than Map<String, dynamic>
class Product {
  final String name;
  final String price;
  final String category;
  final IconData icon;
  final bool inStock;

  const Product({
    required this.name,
    required this.price,
    required this.category,
    required this.icon,
    this.inStock = true,
  });
}

void main() {
  runApp(const MaterialApp(home: ProductListPage()));
}

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

  static const List<Product> products = [
    Product(name: 'Wireless Headphones', price: '₹1,999', category: 'Audio',     icon: Icons.headphones),
    Product(name: 'Mechanical Keyboard', price: '₹3,499', category: 'Computing', icon: Icons.keyboard),
    Product(name: 'USB-C Hub',           price: '₹1,299', category: 'Computing', icon: Icons.usb),
    Product(name: 'Monitor Stand',       price: '₹899',   category: 'Desk',      icon: Icons.monitor),
    Product(name: 'Webcam HD',           price: '₹2,199', category: 'Video',     icon: Icons.videocam,  inStock: false),
    Product(name: 'Laptop Sleeve',       price: '₹599',   category: 'Bags',      icon: Icons.work),
    Product(name: 'Desk Lamp LED',       price: '₹749',   category: 'Lighting',  icon: Icons.lightbulb),
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Products')),
      body: ListView.builder(
        padding: const EdgeInsets.symmetric(vertical: 8),
        itemCount: products.length,
        // 2. itemBuilder is now a single clean line
        itemBuilder: (context, index) => ProductCard(product: products[index]),
      ),
    );
  }
}

// 3. The extracted item widget — all card UI lives here
class ProductCard extends StatelessWidget {
  final Product product;

  const ProductCard({super.key, required this.product});

  @override
  Widget build(BuildContext context) {
    final scheme = Theme.of(context).colorScheme;
    return Card(
      margin: const EdgeInsets.symmetric(horizontal: 12, vertical: 6),
      child: Padding(
        padding: const EdgeInsets.all(14),
        child: Row(
          children: [
            // Icon container
            Container(
              width: 56,
              height: 56,
              decoration: BoxDecoration(
                color: scheme.primaryContainer,
                borderRadius: BorderRadius.circular(10),
              ),
              child: Icon(product.icon, color: scheme.primary, size: 28),
            ),
            const SizedBox(width: 16),
            // Text content
            Expanded(
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(
                    product.name,
                    style: const TextStyle(fontWeight: FontWeight.bold, fontSize: 15),
                  ),
                  const SizedBox(height: 4),
                  Text(
                    product.category,
                    style: TextStyle(color: Colors.grey.shade600, fontSize: 12),
                  ),
                ],
              ),
            ),
            // Price + stock badge
            Column(
              crossAxisAlignment: CrossAxisAlignment.end,
              children: [
                Text(
                  product.price,
                  style: TextStyle(
                    color: scheme.primary,
                    fontWeight: FontWeight.bold,
                    fontSize: 15,
                  ),
                ),
                const SizedBox(height: 4),
                Container(
                  padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 2),
                  decoration: BoxDecoration(
                    color: product.inStock
                        ? Colors.green.shade100
                        : Colors.red.shade100,
                    borderRadius: BorderRadius.circular(4),
                  ),
                  child: Text(
                    product.inStock ? 'In stock' : 'Out of stock',
                    style: TextStyle(
                      fontSize: 11,
                      color: product.inStock ? Colors.green.shade800 : Colors.red.shade800,
                    ),
                  ),
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

5. ListView.separated — Dividers and Gaps

ListView.separated is a variant that adds a separator widget between each item. It requires one extra parameter — separatorBuilder — and renders it between every pair of adjacent items (so 10 items get 9 separators):

import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: ContactListPage()));
}

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

  static const List<Map<String, String>> contacts = [
    {'name': 'Alice Johnson',  'role': 'Designer',        'initial': 'A'},
    {'name': 'Bob Smith',      'role': 'Developer',       'initial': 'B'},
    {'name': 'Carol White',    'role': 'Product Manager', 'initial': 'C'},
    {'name': 'David Lee',      'role': 'QA Engineer',     'initial': 'D'},
    {'name': 'Eva Martinez',   'role': 'DevOps',          'initial': 'E'},
    {'name': 'Frank Chen',     'role': 'Data Scientist',  'initial': 'F'},
    {'name': 'Grace Kim',      'role': 'iOS Developer',   'initial': 'G'},
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Contacts')),
      body: ListView.separated(
        itemCount: contacts.length,
        // The list item
        itemBuilder: (context, index) {
          final contact = contacts[index];
          return ListTile(
            leading: CircleAvatar(
              child: Text(contact['initial']!),
            ),
            title: Text(contact['name']!),
            subtitle: Text(contact['role']!),
            trailing: const Icon(Icons.message_outlined),
            onTap: () {},
          );
        },
        // The separator between items
        separatorBuilder: (context, index) => const Divider(
          height: 1,
          indent: 72,        // aligns with the text, not the avatar
          endIndent: 16,
        ),
      ),
    );
  }
}

// ── Other separator options ───────────────────────────────────────────────

// Option 2: Vertical gap between cards
separatorBuilder: (context, index) => const SizedBox(height: 8),

// Option 3: Section headers every 5 items
separatorBuilder: (context, index) {
  if ((index + 1) % 5 == 0) {
    return Container(
      color: Colors.grey.shade100,
      padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
      child: Text(
        'Section ${(index + 1) ~/ 5 + 1}',
        style: const TextStyle(fontWeight: FontWeight.bold),
      ),
    );
  }
  return const Divider(height: 1);
},

6. Stateful Lists — Adding and Removing Items

When the list changes — items added, deleted, or reordered — the widget must be StatefulWidget and every mutation must happen inside setState(). Here is a complete example with add and swipe-to-delete:

import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: TodoListPage()));
}

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

  @override
  State<TodoListPage> createState() => _TodoListPageState();
}

class _TodoListPageState extends State<TodoListPage> {
  final List<String> _items = ['Buy groceries', 'Walk the dog', 'Read Flutter docs'];
  final TextEditingController _controller = TextEditingController();

  void _addItem() {
    final text = _controller.text.trim();
    if (text.isEmpty) return;
    setState(() {           // ← always mutate inside setState
      _items.add(text);
    });
    _controller.clear();
  }

  void _removeItem(int index) {
    final removed = _items[index];
    setState(() {
      _items.removeAt(index);
    });
    // Undo snackbar
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text('"$removed" removed'),
        action: SnackBarAction(
          label: 'Undo',
          onPressed: () => setState(() => _items.insert(index, removed)),
        ),
      ),
    );
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('To-Do (${_items.length})'),
      ),
      body: Column(
        children: [
          // Add item field
          Padding(
            padding: const EdgeInsets.all(12),
            child: Row(
              children: [
                Expanded(
                  child: TextField(
                    controller: _controller,
                    decoration: const InputDecoration(
                      hintText: 'Add a task...',
                      border: OutlineInputBorder(),
                      contentPadding: EdgeInsets.symmetric(horizontal: 12, vertical: 10),
                    ),
                    onSubmitted: (_) => _addItem(),
                  ),
                ),
                const SizedBox(width: 8),
                FilledButton.icon(
                  onPressed: _addItem,
                  icon: const Icon(Icons.add),
                  label: const Text('Add'),
                ),
              ],
            ),
          ),
          // The list
          Expanded(
            child: _items.isEmpty
                ? const Center(child: Text('No tasks yet — add one above!'))
                : ListView.builder(
                    itemCount: _items.length,
                    itemBuilder: (context, index) {
                      return Dismissible(
                        key: ValueKey(_items[index]),    // unique key required
                        direction: DismissDirection.endToStart,
                        background: Container(
                          alignment: Alignment.centerRight,
                          padding: const EdgeInsets.only(right: 20),
                          color: Colors.red,
                          child: const Icon(Icons.delete, color: Colors.white),
                        ),
                        onDismissed: (_) => _removeItem(index),
                        child: ListTile(
                          leading: const Icon(Icons.check_box_outline_blank),
                          title: Text(_items[index]),
                          trailing: IconButton(
                            icon: const Icon(Icons.delete_outline, color: Colors.red),
                            onPressed: () => _removeItem(index),
                          ),
                        ),
                      );
                    },
                  ),
          ),
        ],
      ),
    );
  }
}

7. Pull-to-Refresh with RefreshIndicator

Wrapping ListView.builder in a RefreshIndicator adds the standard pull-to-refresh gesture. The onRefresh callback must return a Future — the spinner shows until the future completes:

import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: RefreshListPage()));
}

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

  @override
  State<RefreshListPage> createState() => _RefreshListPageState();
}

class _RefreshListPageState extends State<RefreshListPage> {
  List<String> _items = List.generate(10, (i) => 'Original item ${i + 1}');

  // Simulates an API refresh — replace with your real fetch logic
  Future<void> _onRefresh() async {
    await Future.delayed(const Duration(seconds: 2)); // simulate network delay
    setState(() {
      final timestamp = DateTime.now().minute;
      _items = List.generate(10, (i) => 'Refreshed at :$timestamp — item ${i + 1}');
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Pull to Refresh')),
      body: RefreshIndicator(
        onRefresh: _onRefresh,   // ← must return Future<void>
        child: ListView.builder(
          // physics must allow overscroll for pull-to-refresh to work
          physics: const AlwaysScrollableScrollPhysics(),
          itemCount: _items.length,
          itemBuilder: (context, index) => ListTile(
            leading: const Icon(Icons.article_outlined),
            title: Text(_items[index]),
          ),
        ),
      ),
    );
  }
}

8. Loading State and Empty State

Real apps fetch data asynchronously. The list needs to handle three states: loading (show a spinner or skeleton), empty (show a helpful message), and loaded (show the list). Here is the full pattern:

import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: AsyncListPage()));
}

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

  @override
  State<AsyncListPage> createState() => _AsyncListPageState();
}

class _AsyncListPageState extends State<AsyncListPage> {
  List<String> _items = [];
  bool _isLoading = true;
  String? _error;

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

  Future<void> _loadData() async {
    setState(() {
      _isLoading = true;
      _error = null;
    });
    try {
      // Simulate a 1.5-second network fetch
      await Future.delayed(const Duration(milliseconds: 1500));
      setState(() {
        _items = List.generate(12, (i) => 'Post ${i + 1}: Flutter tip of the day');
        _isLoading = false;
      });
    } catch (e) {
      setState(() {
        _error = 'Failed to load data. Tap to retry.';
        _isLoading = false;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Async List')),
      body: _buildBody(),
    );
  }

  Widget _buildBody() {
    // 1. Loading state — spinner while fetch is in progress
    if (_isLoading) {
      return const Center(child: CircularProgressIndicator());
    }

    // 2. Error state — tap to retry
    if (_error != null) {
      return Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Icon(Icons.wifi_off, size: 56, color: Colors.grey),
            const SizedBox(height: 16),
            Text(_error!, textAlign: TextAlign.center),
            const SizedBox(height: 16),
            ElevatedButton.icon(
              onPressed: _loadData,
              icon: const Icon(Icons.refresh),
              label: const Text('Retry'),
            ),
          ],
        ),
      );
    }

    // 3. Empty state — no data after a successful load
    if (_items.isEmpty) {
      return const Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Icon(Icons.inbox_outlined, size: 64, color: Colors.grey),
            SizedBox(height: 16),
            Text('No posts yet', style: TextStyle(fontSize: 18)),
          ],
        ),
      );
    }

    // 4. Loaded state — the actual list
    return RefreshIndicator(
      onRefresh: _loadData,
      child: ListView.builder(
        physics: const AlwaysScrollableScrollPhysics(),
        itemCount: _items.length,
        itemBuilder: (context, index) => ListTile(
          leading: CircleAvatar(child: Text('${index + 1}')),
          title: Text(_items[index]),
          subtitle: Text('Published today'),
        ),
      ),
    );
  }
}

9. Basic Pagination — Load More on Scroll

For large datasets, loading all items at once wastes bandwidth. Detect when the user scrolls near the bottom using a ScrollController, then fetch the next page:

import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: PaginatedListPage()));
}

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

  @override
  State<PaginatedListPage> createState() => _PaginatedListPageState();
}

class _PaginatedListPageState extends State<PaginatedListPage> {
  final ScrollController _scrollController = ScrollController();
  final List<String> _items = [];
  bool _isLoadingMore = false;
  bool _hasMore = true;
  int _page = 0;

  @override
  void initState() {
    super.initState();
    _loadNextPage(); // load the first page immediately
    _scrollController.addListener(_onScroll);
  }

  void _onScroll() {
    // Fire when the user scrolls within 200px of the bottom
    final maxScroll = _scrollController.position.maxScrollExtent;
    final currentScroll = _scrollController.position.pixels;
    if (currentScroll >= maxScroll - 200 && !_isLoadingMore && _hasMore) {
      _loadNextPage();
    }
  }

  Future<void> _loadNextPage() async {
    if (_isLoadingMore) return;
    setState(() => _isLoadingMore = true);

    await Future.delayed(const Duration(milliseconds: 800)); // simulate API

    final newItems = List.generate(
      10,
      (i) => 'Page ${_page + 1} — Item ${_page * 10 + i + 1}',
    );

    setState(() {
      _items.addAll(newItems);
      _page++;
      _isLoadingMore = false;
      if (_page >= 5) _hasMore = false; // stop after 5 pages (50 items total)
    });
  }

  @override
  void dispose() {
    _scrollController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Paginated List (${_items.length} items)')),
      body: ListView.builder(
        controller: _scrollController,   // ← attach the scroll controller
        // Add 1 extra item at the end for the loading indicator
        itemCount: _items.length + (_isLoadingMore || _hasMore ? 1 : 0),
        itemBuilder: (context, index) {
          // Last item — show spinner if loading, or "end of list" message
          if (index == _items.length) {
            return Padding(
              padding: const EdgeInsets.all(16),
              child: Center(
                child: _isLoadingMore
                    ? const CircularProgressIndicator()
                    : const Text(
                        'You have reached the end',
                        style: TextStyle(color: Colors.grey),
                      ),
              ),
            );
          }
          return ListTile(
            leading: CircleAvatar(child: Text('${index + 1}')),
            title: Text(_items[index]),
          );
        },
      ),
    );
  }
}

10. Horizontal Lists and Grid Alternatives

ListView.builder scrolls vertically by default. Set scrollDirection: Axis.horizontal for a horizontal list — common for category chips, featured cards, or image carousels:

// Horizontal scrolling list — each item needs a fixed width
SizedBox(
  height: 120,                        // ← height must be bounded for horizontal lists
  child: ListView.builder(
    scrollDirection: Axis.horizontal, // ← makes it scroll left/right
    padding: const EdgeInsets.symmetric(horizontal: 12),
    itemCount: categories.length,
    itemBuilder: (context, index) {
      final category = categories[index];
      return Container(
        width: 100,                   // ← fixed width for each item
        margin: const EdgeInsets.only(right: 12),
        decoration: BoxDecoration(
          color: category['color'] as Color,
          borderRadius: BorderRadius.circular(12),
        ),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Icon(category['icon'] as IconData, color: Colors.white, size: 36),
            const SizedBox(height: 8),
            Text(
              category['name'] as String,
              style: const TextStyle(color: Colors.white, fontWeight: FontWeight.w600),
            ),
          ],
        ),
      );
    },
  ),
)

// ─────────────────────────────────────────────────────────────────────────

// Combining horizontal featured cards + vertical full list on one screen
ListView(
  children: [
    const Padding(
      padding: EdgeInsets.fromLTRB(16, 16, 0, 8),
      child: Text('Featured', style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold)),
    ),
    // Horizontal list embedded in the vertical scroll
    SizedBox(
      height: 160,
      child: ListView.builder(
        scrollDirection: Axis.horizontal,
        padding: const EdgeInsets.symmetric(horizontal: 12),
        itemCount: 5,
        itemBuilder: (context, index) => Card(
          margin: const EdgeInsets.only(right: 12),
          child: SizedBox(
            width: 140,
            child: Center(child: Text('Featured $index')),
          ),
        ),
      ),
    ),
    const Padding(
      padding: EdgeInsets.fromLTRB(16, 16, 0, 8),
      child: Text('All Items', style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold)),
    ),
    // Regular vertical items below
    ...List.generate(10, (i) => ListTile(title: Text('Item $i'))),
  ],
)

11. shrinkWrap and Nested Lists

The most common layout error with ListView.builder is putting it inside a Column without constraining its height. There are two fixes — choose based on your use case:

// ❌ Wrong — throws "Vertical viewport was given unbounded height"
Column(
  children: [
    const Text('My List'),
    ListView.builder(   // no height constraint — Flutter can't render this
      itemCount: 10,
      itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
    ),
  ],
)

// ─────────────────────────────────────────────────────────────────────────

// ✅ Fix 1: Expanded — preferred for most cases
// ListView fills all remaining space in the Column
Column(
  children: [
    const Text('My List'),
    Expanded(                       // ← gives ListView bounded height
      child: ListView.builder(
        itemCount: 10,
        itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
      ),
    ),
  ],
)

// ─────────────────────────────────────────────────────────────────────────

// ✅ Fix 2: shrinkWrap — for short embedded lists only
// ListView shrinks to fit its content exactly
Column(
  children: [
    const Text('My List'),
    ListView.builder(
      shrinkWrap: true,                               // ← sizes to content
      physics: const NeverScrollableScrollPhysics(),  // ← parent handles scrolling
      itemCount: 5,                                   // keep this small
      itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
    ),
    const Text('More content below the list'),
  ],
)

12. Common Beginner Mistakes

Mistake 1: Missing itemCount — infinite list and index crash

// ❌ Wrong — no itemCount → infinite list, index goes beyond myList.length → crash
ListView.builder(
  itemBuilder: (context, index) => Text(myList[index]), // RangeError!
)

// ✅ Correct — itemCount bounds the index to valid list positions
ListView.builder(
  itemCount: myList.length,
  itemBuilder: (context, index) => Text(myList[index]),
)

Mistake 2: ListView inside Column without Expanded

// ❌ Wrong — throws "Vertical viewport was given unbounded height"
Column(
  children: [
    ListView.builder(itemCount: 10, itemBuilder: ...),
  ],
)

// ✅ Correct
Column(
  children: [
    Expanded(
      child: ListView.builder(itemCount: 10, itemBuilder: ...),
    ),
  ],
)

Mistake 3: Mutating the list without setState — UI never updates

// ❌ Wrong — list changes in memory but Flutter doesn't rebuild
void addItem() {
  myList.add('New Item');   // value changes but UI stays the same
}

// ❌ Also wrong — setState called in the wrong widget (child instead of owner)
// The widget holding ListView.builder doesn't rebuild

// ✅ Correct — always mutate inside setState in the widget that owns the list
void addItem() {
  setState(() {
    myList.add('New Item'); // Flutter rebuilds ListView.builder with the new data
  });
}

Mistake 4: Missing key on Dismissible — wrong items deleted

// ❌ Wrong — using index as key causes Flutter to misidentify items after deletion
Dismissible(
  key: ValueKey(index),      // ← index changes after deletion → wrong item removed
  child: ...,
)

// ✅ Correct — use a unique identifier from the data itself
Dismissible(
  key: ValueKey(myList[index].id),  // ← stable ID tied to the item, not its position
  child: ...,
)

Mistake 5: Hardcoding index instead of using the builder parameter

// ❌ Wrong — ignoring the index parameter and hardcoding a value
ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) => Text(items[0].name), // always shows item 0!
)

// ✅ Correct — use the index parameter that itemBuilder provides
ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) => Text(items[index].name), // ← index changes each call
)

13. Interview Q&A

14. Related Posts