Skip to content
Boring Doc
BreakingHigh impactOfficial migration guidesince 1.17.0landed 1.15.4

Container color optimization

Framework · Official source

What changed?

A new `ColoredBox` widget has been added to the framework, and the `Container` widget has been optimized to use it if a user specifies a `color` instead of a `decoration`.

Original behavior

It is very common to use the `Container` widget as follows:

New behavior

Not stated in the source.

Will this affect my application?

Who is affected
Applications and packages relying on the previous behaviour or signature. Code that uses ColoredBox, Container, BoxDecoration.
Practical impact
Behaviour or API differences that can break builds or change runtime behaviour.
What action should I take?
Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.
APIs mentioned:ColoredBoxContainerBoxDecoration

How do I migrate safely?

Before and after (from the official guide)

dart+5−3
Before
1 testWidgets('Container color', (WidgetTester tester) async {
2 await tester.pumpWidget(Container(color: Colors.red));
3  
4 final Container container = tester.widgetList<Container>().first;
5− expect(container.decoration.color, Colors.red);
6− // Or, a test may have specifically looked for the BoxDecoration, e.g.:
7− expect(find.byType(BoxDecoration), findsOneWidget);
 
 
8 });
After
1 testWidgets('Container color', (WidgetTester tester) async {
2 await tester.pumpWidget(Container(color: Colors.red));
3  
4 final Container container = tester.widgetList<Container>().first;
5+ expect(container.color, Colors.red);
6+ // If your test needed to work directly with the BoxDecoration, it should
7+ // instead look for the ColoredBox, e.g.:
8+ expect(find.byType(BoxDecoration), findsNothing);
9+ expect(find.byType(ColoredBox), findsOneWidget);
10 });
Raw before / after
testWidgets('Container color', (WidgetTester tester) async {
  await tester.pumpWidget(Container(color: Colors.red));

  final Container container = tester.widgetList<Container>().first;
  expect(container.decoration.color, Colors.red);
  // Or, a test may have specifically looked for the BoxDecoration, e.g.:
  expect(find.byType(BoxDecoration), findsOneWidget);
});
testWidgets('Container color', (WidgetTester tester) async {
  await tester.pumpWidget(Container(color: Colors.red));

  final Container container = tester.widgetList<Container>().first;
  expect(container.color, Colors.red);
  // If your test needed to work directly with the BoxDecoration, it should
  // instead look for the ColoredBox, e.g.:
  expect(find.byType(BoxDecoration), findsNothing);
  expect(find.byType(ColoredBox), findsOneWidget);
});
Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)

Tests that assert on the color of a Container or that expected it to create a BoxDecoration need to be modified.

Code before migration:

testWidgets('Container color', (WidgetTester tester) async {
  await tester.pumpWidget(Container(color: Colors.red));

  final Container container = tester.widgetList&#x3C;Container>().first;
  expect(container.decoration.color, Colors.red);
  // Or, a test may have specifically looked for the BoxDecoration, e.g.:
  expect(find.byType(BoxDecoration), findsOneWidget);
});

Code after migration:

testWidgets('Container color', (WidgetTester tester) async {
  await tester.pumpWidget(Container(color: Colors.red));

  final Container container = tester.widgetList&#x3C;Container>().first;
  expect(container.color, Colors.red);
  // If your test needed to work directly with the BoxDecoration, it should
  // instead look for the ColoredBox, e.g.:
  expect(find.byType(BoxDecoration), findsNothing);
  expect(find.byType(ColoredBox), findsOneWidget);
});
Migration assistantAI-generated · grounded in cited sources
AI explanations are not configured
Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.

Evidence & verification

Official migration guide·Verified classification (95%)

Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).

An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.

Source commit
b3045439b7c0
Source last updated
Oct 21, 2026
Last synchronized
Oct 21, 2026
Publication status
published
Publication history
  • Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI explanationAI-generated · grounded in cited sources
AI explanations are not configured
Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.
Was this useful?