Flutter Container Widget Explained: Decoration, Padding, and Constraints

Container is the first widget most Flutter developers learn and the one they keep reaching for years later. It is the everyday box: give it a child and it can add padding, a background colour or gradient, a border, rounded corners, a shadow, a fixed size, and an alignment — all from one widget. This guide explains every property that matters, the rules that trip people up (like why color and decoration clash), and when a leaner widget is the better choice.

Every snippet is paste-ready against current stable Flutter. Drop each one into a Scaffold body to see it render. If you want the wider picture of how boxes fit together, this guide pairs with the Flutter Layout Widgets guide, which covers the constraints model that Container obeys.

Follow me on Instagram@sagnikteaches

We will start with what Container actually is (a bundle of smaller widgets), then walk padding and margin, decoration, sizing and constraints, alignment, and transforms — finishing with the common mistakes and the leaner alternatives worth knowing.

Connect on LinkedInSagnik Bhattacharya

This tutorial is part of a series on Flutter's core widgets. Its closest companions are the Row and Column guide and the Stack and Positioned guide, which cover how to arrange and layer the boxes you build here.

Subscribe on YouTube@codingliquids

What Container really is

Container is a convenience widget. It does not draw anything special itself — instead it composes a stack of simpler widgets only when you use the matching property. Set padding and it wraps a Padding; set decoration and it wraps a DecoratedBox; set constraints, width, or height and it wraps a ConstrainedBox; set alignment and it wraps an Align; set transform and it wraps a Transform. That is why a single widget can do so much — and why, if you only need one of those behaviours, the dedicated widget is lighter.

Container(
  padding: const EdgeInsets.all(16),
  margin: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
  decoration: BoxDecoration(
    color: Colors.white,
    borderRadius: BorderRadius.circular(16),
    boxShadow: const [BoxShadow(color: Colors.black12, blurRadius: 8, offset: Offset(0, 2))],
  ),
  child: const Text('A card-like box'),
)

Padding and margin

The two spacing properties are easy to mix up. Padding is space inside the container, between its edge and the child. Margin is space outside, between the container and its neighbours. Both accept an EdgeInsets.

// Four ways to build EdgeInsets
const EdgeInsets.all(16),                                  // every side
const EdgeInsets.symmetric(horizontal: 24, vertical: 12),  // left/right, top/bottom
const EdgeInsets.only(left: 16, top: 8),                   // specific sides
const EdgeInsets.fromLTRB(16, 8, 16, 24),                  // left, top, right, bottom

A neat detail: the colour or decoration paints the padded area but not the margin. So padding extends the coloured box around the child, while margin pushes the whole coloured box away from its neighbours.

Decoration: colour, borders, gradients, and shadows

For a plain fill, the color shorthand is enough. The moment you want a border, rounded corners, a gradient, a shadow, or a background image, you move to decoration: BoxDecoration(...) — and you must remove color (more on that clash below).

Container(
  width: 200,
  height: 120,
  decoration: BoxDecoration(
    gradient: const LinearGradient(
      colors: [Color(0xFF2563EB), Color(0xFF22D3EE)],
      begin: Alignment.topLeft,
      end: Alignment.bottomRight,
    ),
    borderRadius: BorderRadius.circular(20),
    border: Border.all(color: Colors.white, width: 2),
    boxShadow: const [
      BoxShadow(color: Colors.black26, blurRadius: 16, offset: Offset(0, 6)),
    ],
  ),
  child: const Center(child: Text('Gradient card', style: TextStyle(color: Colors.white))),
)

The most-used BoxDecoration fields:

• color — a solid fill (inside the decoration, not on the Container).
• border — Border.all(...) or per-side borders.
• borderRadius — rounded corners (ignored if shape is a circle).
• boxShadow — a list of shadows for elevation.
• gradient — LinearGradient, RadialGradient, or SweepGradient.
• image — a DecorationImage background.
• shape — BoxShape.rectangle (default) or BoxShape.circle.

There is also a foregroundDecoration that paints over the child — handy for an overlay tint or a "sold out" badge effect.

The color vs decoration rule

Setting both color and decoration on a Container throws an assertion. The reason is simple: color is a shorthand for a BoxDecoration with that colour, so providing both is ambiguous. The fix is to move the colour inside the decoration.

// Throws: "Cannot provide both a color and a decoration"
// Container(color: Colors.blue, decoration: BoxDecoration(borderRadius: ...))

// Correct: colour lives inside the decoration
Container(
  decoration: BoxDecoration(
    color: Colors.blue,
    borderRadius: BorderRadius.circular(12),
  ),
)

Sizing and constraints

How big is a Container? It depends on what you give it and what its parent allows. The behaviour is worth memorising:

• No child, no size → it expands to fill the space the parent permits.
• A child, no explicit size → it shrinks to wrap the child.
• width/height set → it tries to be exactly that size, within the parent's constraints.
• constraints set → a BoxConstraints gives min/max bounds, e.g. a minimum height with a flexible maximum.

// Exact size
Container(width: 120, height: 120, color: Colors.amber),

// Constraint range instead of a fixed size
Container(
  constraints: const BoxConstraints(minWidth: 100, maxWidth: 240, minHeight: 48),
  color: Colors.teal,
  child: const Text('Flexible within bounds'),
)

The key caveat — the one behind most "my Container ignores its size" questions — is that the parent's constraints win. If a parent forces a tight width, asking the Container for a different width has no effect. When that happens, look up the tree at what is constraining you; the RenderFlex overflow guide walks through reading those constraints.

Alignment and transform

Set alignment to position the child within the container's bounds — which also makes the container grow to fill available space so it has room to align inside.

Container(
  height: 160,
  color: Colors.black12,
  alignment: Alignment.bottomRight,
  padding: const EdgeInsets.all(12),
  child: const Text('Bottom-right'),
)

The transform property applies a Matrix4 — rotate, scale, skew, or translate the whole container. Add transformAlignment to choose the pivot point.

Container(
  transform: Matrix4.rotationZ(0.05),
  transformAlignment: Alignment.center,
  padding: const EdgeInsets.all(16),
  color: Colors.deepPurple.shade50,
  child: const Text('Slightly tilted'),
)

When to use something leaner than Container

Because Container only builds the parts you use, a bare Container() is cheap — but reaching for it out of habit can hide intent. Prefer the specific widget when you need exactly one behaviour:

• Only spacing inside → use Padding.
• Only a fixed size, or a gap between siblings → use SizedBox.
• Only a background colour → use ColoredBox.
• Only rounded corners or a decoration → use DecoratedBox.
• Only centring a child → use Center (or Align).

Reach for Container when you genuinely combine several of these — padding plus a decoration plus a size — which is exactly the card-like box it excels at.

Common Container mistakes

• Setting color and decoration together. Put the colour inside the BoxDecoration.
• Expecting a size the parent forbids. Parent constraints override width/height; check what is constraining the Container.
• Rounded corners that do not clip the child. borderRadius rounds the decoration, not the child. To clip a child (like an image) to the corners, add clipBehavior: Clip.antiAlias or wrap the child in a ClipRRect.
• Using margin for spacing between list items. A SizedBox or ListView.separated is clearer for gaps between siblings.
• Nesting many Containers for one effect. Combine the properties into a single Container, or use the leaner dedicated widget.

Frequently asked questions

What is a Container in Flutter?

It is a convenience widget that bundles Padding, DecoratedBox, ConstrainedBox, Align, and Transform. A single Container can add padding and margin, paint a colour or decoration, apply size constraints, align its child, and transform itself.

Why can't I use color and decoration together?

Because color is shorthand for a BoxDecoration with that colour, so setting both is ambiguous and throws. Put the colour inside the decoration as BoxDecoration(color: ...).

What is the difference between padding and margin?

Padding is space inside the Container (between its edge and the child); margin is space outside (between the Container and its neighbours). Both take EdgeInsets.

How big is a Container without a child?

With no child and no size, it fills the space the parent allows. With a child and no size, it shrinks to fit the child. Set width/height or constraints for explicit control — though parent constraints can still override.

Further reads

Keep going with the tutorials that pair with this guide:

• Flutter Development Guide 2026 — the full Flutter hub.
• Flutter Layout Widgets: The Complete Guide — the constraints model Container obeys, and every layout widget.
• Flutter Row and Column: MainAxis, CrossAxis, and Spacing — arrange containers in a line.
• Flutter Stack and Positioned — layer and overlap containers.
• How to Fix RenderFlex Overflowed in Flutter — read the constraints when a box won't size.

Sources: Flutter documentation — Container, BoxDecoration, EdgeInsets, and BoxConstraints API references, plus the Layout and "Understanding constraints" guides (docs.flutter.dev). Verified against current stable Flutter.