How to Use LayoutBuilder in Flutter: Syntax and Examples

Use LayoutBuilder in Flutter to build widgets that adapt to their parent's size by accessing the BoxConstraints in its builder function. Wrap your widget tree inside LayoutBuilder and use the constraints to adjust layout dynamically.

Syntax

The LayoutBuilder widget takes a builder function with two parameters: BuildContext and BoxConstraints. The BoxConstraints tells you the maximum and minimum width and height the parent allows. You return a widget tree that can adapt based on these constraints.

dart

LayoutBuilder(
  builder: (BuildContext context, BoxConstraints constraints) {
    // Use constraints.maxWidth, constraints.maxHeight
    return Container();
  },
)

Example

This example shows a Container with a width that changes color based on the available width from the parent. If the width is more than 200 pixels, it shows green; otherwise, red.

dart

import 'package:flutter/material.dart';

void main() => runApp(const MyApp());

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

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: Scaffold(
        body: Center(
          child: ResponsiveBox(),
        ),
      ),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(
      builder: (context, constraints) {
        final color = constraints.maxWidth > 200 ? Colors.green : Colors.red;
        return Container(
          width: constraints.maxWidth * 0.8,
          height: 100,
          color: color,
          alignment: Alignment.center,
          child: Text('Width: ${constraints.maxWidth.toStringAsFixed(1)}',
              style: const TextStyle(color: Colors.white, fontSize: 18)),
        );
      },
    );
  }
}

Output

A centered colored box that is green if parent width > 200px, red otherwise, showing the current width as text.

Common Pitfalls

• Using LayoutBuilder inside widgets that do not constrain size (like Column) can cause infinite size errors.
• Not using the constraints to adapt layout defeats the purpose of LayoutBuilder.
• Overusing LayoutBuilder can hurt performance; use only when layout depends on parent size.

dart

/* Wrong: Using LayoutBuilder inside Column without constraints causes error */
Column(
  children: [
    LayoutBuilder(
      builder: (context, constraints) {
        return Container(width: constraints.maxWidth, height: 50, color: Colors.blue);
      },
    ),
  ],
);

/* Right: Wrap LayoutBuilder in Expanded or SizedBox to provide constraints */
Column(
  children: [
    SizedBox(
      height: 50,
      child: LayoutBuilder(
        builder: (context, constraints) {
          return Container(width: constraints.maxWidth, height: 50, color: Colors.blue);
        },
      ),
    ),
  ],
);

Quick Reference

LayoutBuilder Cheat Sheet:

• builder: Function with BuildContext and BoxConstraints.
• BoxConstraints: Provides maxWidth, maxHeight, minWidth, minHeight.
• Use constraints to build responsive widgets.
• Wrap in widgets that provide constraints (e.g., SizedBox, Expanded).

Key Takeaways

Use LayoutBuilder to get parent size constraints and build responsive widgets accordingly.

The builder function provides BoxConstraints with max and min width/height to guide layout.

Avoid using LayoutBuilder where parent size is unbounded to prevent layout errors.

Wrap LayoutBuilder in widgets that provide size constraints like SizedBox or Expanded.

Use LayoutBuilder only when layout depends on parent size to keep performance optimal.