avoid_hooks_outside_build

v0.8.0WarningConfigurableHook Rules

This rule flags a useX() call that happens outside a hook context — anywhere that is not a HookWidget.build, a HookBuilder’s builder, or another hook function.

Why use this rule

flutter_hooks stores hook state in a list attached to the element and matches each call to its slot by position. That bookkeeping only exists while a hook widget is building. Call a hook from an event handler, a lifecycle method, or a plain helper and there is no hook context to write into: you get an exception, or worse, state written into an unrelated widget’s slots.

Together with avoid_conditional_hooks and avoid_misused_hooks, this covers the rules of hooks: call them unconditionally, the same number of times, from a hook context.

See also: flutter_hooks rules

Don’t

class MyWidget extends HookWidget {
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () {
        // No hook context inside a callback
        final counter = useState(0);
      },
      child: const Text('tap'),
    );
  }
}

Do

class MyWidget extends HookWidget {
  @override
  Widget build(BuildContext context) {
    // Called directly in build — valid
    final counter = useState(0);

    return ElevatedButton(
      onPressed: () => counter.value++,
      child: Text('${counter.value}'),
    );
  }
}

// Composing hooks inside another hook is valid too
ValueNotifier<int> useCounter() {
  return useState(0);
}

Known limitations

Hooks are recognised by name: an unqualified call whose name matches use followed by an uppercase letter or digit. A hook renamed to something else is not detected, and a plain function following that naming convention is treated as a hook.

Turning this rule off

This rule is in the recommended preset, so it is on with preset: recommended or preset: opinionated. Add it to preset: core with avoid_hooks_outside_build: true.

To turn it off:

rules:
  avoid_hooks_outside_build: false

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

many_lints:
  rules:
    avoid_hooks_outside_build:
      additional_methods: [buildBody]

rules:
  avoid_hooks_outside_build:
    additional_methods: [buildBody]

Option	Type	Default	Description
`additional_methods`	list of strings	`[]`	Further methods of a hook widget treated as valid hook contexts, alongside `build`

avoid_misused_hooks — Don’t call hooks inside loops.
avoid_conditional_hooks — Never call hooks inside conditionals, loops, or ternaries.
avoid_unnecessary_hook_widgets — Don’t extend HookWidget if you never call any hooks.
avoid_ref_watch_outside_build — Subscribe only in build; read once everywhere else.