Overview

Container is a convenience widget that combines common painting, positioning, and sizing widgets for its child.

Container combines several basic widgets (Padding, Align, ColoredBox, DecoratedBox, ConstrainedBox, Transform, etc.) into a single widget, simplifying common layout and styling tasks. An empty Container tries to occupy as much space as possible, but when it has a child, it sizes itself to the child.

See: https://api.flutter.dev/flutter/widgets/Container-class.html

When to use it?

  • When applying styles like background color, borders, shadows to a widget
  • When adding margin or padding around a widget
  • When constraining or fixing a widget’s size
  • When applying multiple layout properties at once
  • When creating card UIs, button backgrounds, section dividers, etc.

Basic Usage

// Simplest example
const widget = Container({
  width: 200,
  height: 100,
  color: 'blue',
  child: Text('Hello Container!')
});

// Using padding and margin
const paddedContainer = Container({
  margin: EdgeInsets.all(10),
  padding: EdgeInsets.symmetric({ horizontal: 20, vertical: 10 }),
  color: 'lightgray',
  child: Text('Padded Text')
});

Props

width

Value: number | undefined

Specifies the width of the Container in pixels. If not specified, it’s determined by the child’s size or parent’s constraints.

Container({ width: 300, color: 'red' })

height

Value: number | undefined

Specifies the height of the Container in pixels. If not specified, it’s determined by the child’s size or parent’s constraints.

Container({ height: 150, color: 'green' })

constraints

Value: Constraints | undefined

Specifies the minimum/maximum width and height of the Container. Provides more flexible size control than width/height.

Container({
  constraints: Constraints({
    minWidth: 100,
    maxWidth: 300,
    minHeight: 50,
    maxHeight: 200
  }),
  color: 'orange'
})

padding

Value: EdgeInsets (default: none)

The spacing between the Container’s edge and its child widget.

// Same padding on all sides
Container({
  padding: EdgeInsets.all(16),
  color: 'lightblue',
  child: Text('Padded')
})

// Different padding per side
Container({
  padding: EdgeInsets.only({ top: 20, left: 10, right: 10, bottom: 5 }),
  color: 'pink'
})

margin

Value: EdgeInsets (default: none)

The spacing between the Container and other widgets outside it.

Container({
  margin: EdgeInsets.symmetric({ horizontal: 20, vertical: 10 }),
  color: 'yellow',
  child: Text('Margined')
})

alignment

Value: Alignment | undefined

Specifies the alignment position of the child widget within the Container. x and y values range from -1 to 1.

Container({
  width: 200,
  height: 200,
  color: 'gray',
  alignment: Alignment.center,
  child: Text('Centered')
})

// Available alignment constants
// Alignment.topLeft, Alignment.topCenter, Alignment.topRight
// Alignment.centerLeft, Alignment.center, Alignment.centerRight
// Alignment.bottomLeft, Alignment.bottomCenter, Alignment.bottomRight

color

Value: string | undefined

Specifies the background color of the Container. Cannot be used with decoration.

⚠️ Warning: Using with decoration prop will cause an error.

Container({
  width: 100,
  height: 100,
  color: '#FF5733'
})

decoration

Value: Decoration | undefined

Specifies complex styling for the Container (borders, rounded corners, shadows, etc.).

⚠️ Warning: Cannot be used with color prop. Specify color inside decoration instead.

Container({
  width: 150,
  height: 150,
  decoration: BoxDecoration({
    color: 'white',
    border: Border.all({ color: 'black', width: 2 }),
    borderRadius: BorderRadius.circular(10),
    boxShadow: [
      BoxShadow({
        color: 'rgba(0, 0, 0, 0.3)',
        blurRadius: 10,
        offset: { x: 5, y: 5 }
      })
    ]
  }),
  child: Text('Decorated')
})

clipped

Value: boolean | undefined (default: false)

Determines whether to clip the child widget according to the decoration’s shape.

⚠️ Warning: When clipped is true, decoration is required.

Container({
  width: 100,
  height: 100,
  clipped: true,
  decoration: BoxDecoration({
    shape: 'circle',
    color: 'blue'
  }),
  child: Image({ src: 'photo.jpg', fit: 'cover' })
})

transform

Value: Matrix4 | undefined

Applies transformations like rotation, scaling, skewing to the Container.

Container({
  color: 'purple',
  transform: Matrix4.rotationZ(Math.PI / 4), // 45 degree rotation
  child: Text('Rotated')
})

transformAlignment

Value: Alignment | undefined

Specifies the origin point for transformations. Defaults to the Container’s center.

Container({
  width: 100,
  height: 100,
  color: 'green',
  transform: Matrix4.rotationZ(Math.PI / 6),
  transformAlignment: Alignment.topLeft, // Rotate around top-left corner
  child: Text('Transform')
})

child

Value: Widget | undefined

The child widget to display inside the Container.

Container({
  padding: EdgeInsets.all(20),
  color: 'lightgray',
  child: Column({
    children: [
      Text('Title'),
      Text('Subtitle')
    ]
  })
})

Practical Examples

Creating a Card UI

const card = Container({
  margin: EdgeInsets.all(16),
  padding: EdgeInsets.all(16),
  decoration: BoxDecoration({
    color: 'white',
    borderRadius: BorderRadius.circular(12),
    boxShadow: [
      BoxShadow({
        color: 'rgba(0, 0, 0, 0.1)',
        blurRadius: 8,
        offset: { x: 0, y: 2 }
      })
    ]
  }),
  child: Column({
    crossAxisAlignment: 'start',
    children: [
      Text('Card Title', { style: TextStyle({ fontSize: 18, fontWeight: 'bold' }) }),
      SizedBox({ height: 8 }),
      Text('Card content goes here...')
    ]
  })
});

Creating a Circular Avatar

const avatar = Container({
  width: 80,
  height: 80,
  clipped: true,
  decoration: BoxDecoration({
    shape: 'circle',
    border: Border.all({ color: 'blue', width: 3 })
  }),
  child: Image({
    src: 'profile.jpg',
    fit: 'cover'
  })
});

Styling a Button

const customButton = GestureDetector({
  onTap: () => console.log('Button tapped'),
  child: Container({
    padding: EdgeInsets.symmetric({ horizontal: 24, vertical: 12 }),
    decoration: BoxDecoration({
      color: 'blue',
      borderRadius: BorderRadius.circular(8)
    }),
    child: Text('Click Me', {
      style: TextStyle({ color: 'white', fontSize: 16 })
    })
  })
});

Important Notes

  • Cannot use color and decoration simultaneously. When using decoration, specify color inside it.
  • When clipped is set to true, decoration is required.
  • A Container without a child and without size constraints tries to occupy as much space as possible.
  • When using transform, be aware that the transformed Container might overlap with other widgets.
  • Using border in decoration automatically adds padding.
  • DecoratedBox: Use when only decoration is needed
  • ColoredBox: Use when only background color is needed
  • Padding: Use when only margin or padding is needed
  • SizedBox: Use when only fixed size is needed
  • ConstrainedBox: Use when only size constraints are needed
  • Align: Use when only alignment is needed
ConstraintsTransformBox CustomPaint