Overview

ConstrainedBox is a widget that imposes additional constraints on its child widget. It combines the constraints from its parent with its own defined constraints to control the child’s size.

Reference: https://api.flutter.dev/flutter/widgets/ConstrainedBox-class.html

When to Use

• When you want to limit the minimum or maximum size of a widget
• When child widgets should only have sizes within a specific range
• When size constraints are needed in responsive layouts
• When you want to ensure minimum height in scrollable areas
• When limiting the maximum size of images or videos

Basic Usage

// Setting minimum size
ConstrainedBox({
  constraints: new Constraints({
    minWidth: 100,
    minHeight: 100
  }),
  child: Container({
    color: 'blue'
  })
})

// Setting maximum size
ConstrainedBox({
  constraints: new Constraints({
    maxWidth: 200,
    maxHeight: 200
  }),
  child: Container({
    color: 'red',
    width: 300,  // Limited to 200
    height: 300  // Limited to 200
  })
})

// Setting fixed size
ConstrainedBox({
  constraints: Constraints.tight({ width: 150, height: 150 }),
  child: Container({
    color: 'green'
  })
})

Props

constraints (required)

Type: Constraints

The constraints to impose on the child widget. Constraints has the following properties:

• minWidth: Minimum width (default: 0)
• maxWidth: Maximum width (default: Infinity)
• minHeight: Minimum height (default: 0)
• maxHeight: Maximum height (default: Infinity)

// Various constraint examples
ConstrainedBox({
  constraints: new Constraints({
    minWidth: 100,
    maxWidth: 300,
    minHeight: 50,
    maxHeight: 200
  }),
  child: child
})

child (optional)

Type: Widget | undefined

The child widget to which the constraints will be applied.

Constraints Constructors

Constraints provides several convenience constructors:

// Default constructor
new Constraints({
  minWidth: 0,
  maxWidth: Infinity,
  minHeight: 0,
  maxHeight: Infinity
})

// Tight constraints (fixed size)
Constraints.tight({ width: 100, height: 100 })

// Loose constraints (only max size limited)
Constraints.loose({ width: 200, height: 200 })

// Expand (expand to parent size)
Constraints.expand()  // Expand in all directions
Constraints.expand({ width: 300 })  // Width is 300, height expands
Constraints.expand({ height: 400 })  // Height is 400, width expands

Constraint Combination

ConstrainedBox combines parent constraints with its own constraints:

// Parent constraints: min(50, 50), max(200, 200)
// ConstrainedBox constraints: min(100, 100), max(150, 150)
// Result: min(100, 100), max(150, 150)

Container({
  constraints: new Constraints({
    minWidth: 50,
    maxWidth: 200,
    minHeight: 50,
    maxHeight: 200
  }),
  child: ConstrainedBox({
    constraints: new Constraints({
      minWidth: 100,
      maxWidth: 150,
      minHeight: 100,
      maxHeight: 150
    }),
    child: Container({ color: 'blue' })
  })
})

Practical Examples

Example 1: Ensuring Minimum Button Size

const MinSizeButton = ({ onPressed, child, minWidth = 88, minHeight = 36 }) => {
  return ConstrainedBox({
    constraints: new Constraints({
      minWidth: minWidth,
      minHeight: minHeight
    }),
    child: ElevatedButton({
      onPressed: onPressed,
      child: child
    })
  });
};

// Usage
MinSizeButton({
  onPressed: () => console.log('clicked'),
  child: Text('OK')  // Minimum size ensured even with short text
})

Example 2: Limiting Image Size

const ConstrainedImage = ({ src, maxSize = 300 }) => {
  return Container({
    decoration: BoxDecoration({
      border: Border.all({ color: '#E0E0E0' }),
      borderRadius: BorderRadius.circular(8)
    }),
    child: ConstrainedBox({
      constraints: new Constraints({
        maxWidth: maxSize,
        maxHeight: maxSize
      }),
      child: Image({
        src: src,
        objectFit: 'contain'
      })
    })
  });
};

Example 3: Responsive Card

const ResponsiveCard = ({ title, content }) => {
  return ConstrainedBox({
    constraints: new Constraints({
      minHeight: 100,
      maxWidth: 400
    }),
    child: Card({
      child: Padding({
        padding: EdgeInsets.all(16),
        child: Column({
          crossAxisAlignment: CrossAxisAlignment.start,
          mainAxisSize: MainAxisSize.min,
          children: [
            Text(title, {
              style: TextStyle({
                fontSize: 20,
                fontWeight: 'bold'
              })
            }),
            SizedBox({ height: 8 }),
            Text(content, {
              style: TextStyle({
                fontSize: 16,
                color: '#666'
              })
            })
          ]
        })
      })
    })
  });
};

Example 4: Minimum Height for Scrollable Area

const ScrollableContent = ({ children, minHeight = 300 }) => {
  return SingleChildScrollView({
    child: ConstrainedBox({
      constraints: new Constraints({
        minHeight: minHeight
      }),
      child: Column({
        children: children
      })
    })
  });
};

Example 5: Constrained Box with Aspect Ratio

const ConstrainedAspectBox = ({ 
  child, 
  aspectRatio = 16/9, 
  maxWidth = 600 
}) => {
  return ConstrainedBox({
    constraints: new Constraints({
      maxWidth: maxWidth
    }),
    child: AspectRatio({
      aspectRatio: aspectRatio,
      child: Container({
        decoration: BoxDecoration({
          color: '#F5F5F5',
          borderRadius: BorderRadius.circular(12)
        }),
        child: child
      })
    })
  });
};

// Usage example: Video player
ConstrainedAspectBox({
  aspectRatio: 16/9,
  maxWidth: 800,
  child: VideoPlayer({ url: 'video.mp4' })
})

Nested ConstrainedBox

When nesting multiple ConstrainedBoxes, the most restrictive constraint applies:

ConstrainedBox({
  constraints: new Constraints({ minWidth: 200, minHeight: 200 }),
  child: ConstrainedBox({
    constraints: new Constraints({ minWidth: 100, minHeight: 100 }),
    child: Container({ color: 'blue' })
  })
})
// Result: Minimum size is 200x200

Important Notes

• Parent constraints always take precedence
• Conflicting constraints result in the most restrictive being applied
• With infinite size constraints, the child’s intrinsic size is used
• Too much nesting can impact layout performance
• Tight constraints completely ignore the child’s size

Related Widgets

• Container: Provides the same functionality with constraints property
• SizedBox: Simple way to set fixed size
• LimitedBox: Limits size only in infinite constraints
• UnconstrainedBox: Removes constraints from child
• OverflowBox: Allows child to exceed parent constraints