avoid_too_many_widgets_per_build

v1.0.0WarningConfigurableWidget Best Practices

This rule flags a build method that creates more widgets than the configured budget.

Why use this rule

This is the breadth counterpart to avoid_deep_widget_nesting. A tree can be shallow and still be too much for one method: thirty widgets in one build is a screen, a card, a header and a footer sharing a single scope, where nothing has a name and nothing can be reused or tested on its own.

The two metrics catch different problems, and a build can fail either without the other. Depth is about how far right the code runs; this is about how much of the screen one method owns.

Build methods are matched on their return type, not their name, so build, buildHeader and a Widget _row() helper are all measured — an extracted helper does not escape the budget just by being called something else. A build that returns something other than a widget is never measured.

Widgets built inside a builder: closure are counted separately, since that closure is its own build function.

This rule is in the pedantic preset: a widget budget is a house style.

Don’t

@override
Widget build(BuildContext context) => Column(
      children: [
        // the header: 6 widgets
        // the form: 12 widgets
        // the footer: 8 widgets
        // ... 30 in one method, none of them named
      ],
    );

Do

@override
Widget build(BuildContext context) => const Column(
      children: [
        _SettingsHeader(),
        _SettingsForm(),
        _SettingsFooter(),
      ],
    );

Enabling this rule

This rule is in the pedantic preset, so it is enabled by preset: pedantic or by name:

rules:
  avoid_too_many_widgets_per_build:
    enabled: true

many_lints:
  rules:
    avoid_too_many_widgets_per_build:
      max_widgets: 25

rules:
  avoid_too_many_widgets_per_build:
    max_widgets: 25

Option	Type	Default	Description
`max_widgets`	int	`20`	How many widgets one build method may create

Turning this rule off

To disable this rule:

rules:
  avoid_too_many_widgets_per_build: false

To keep the rule on but skip certain paths, use per-rule exclude.

avoid_deep_widget_nesting — Keep a widget tree within a nesting budget.
prefer_extracting_callbacks — Keep long callbacks out of the widget tree.
avoid_returning_widgets — Extract widget helper methods into separate widget classes.
avoid_single_child_in_multi_child_widgets — Don’t use Column, Row, or other multi-child widgets with only one child.