FocusNode: Programmatically Managing Widget Focus

WHY IT EXISTS: Flutter needs a way to manage which widget is currently receiving keyboard input. While simple apps can rely on default behavior, complex UIs like forms or keyboard-navigable interfaces require a way to explicitly control, move, and listen to focus changes. FocusNode provides this granular control.

THE MENTAL MODEL: Think of a FocusNode as a remote control for a widget's focus. It's a persistent object that lives outside the ephemeral build cycle. You create this "remote," pair it with a widget (like a TextField), and then use the remote to tell the widget to grab focus, release focus, or to listen for when its focus state changes. These nodes form a tree structure that mirrors the widget hierarchy, determining how focus moves and how keyboard events bubble up.

HOW IT WORKS: A FocusNode is a ChangeNotifier, meaning you can add listeners to react to focus changes. They must be created in a StatefulWidget's initState and cleaned up in dispose to prevent memory leaks and unexpected behavior. You then attach the node to a focusable widget, like a TextField, via its focusNode property. To programmatically give focus, you call focusNode.requestFocus(). To release it, focusNode.unfocus(). Key events are sent to the node with primary focus. If that node's onKeyEvent callback ignores the event, it propagates up the focus tree to its parent until handled or discarded.

WHEN TO USE IT: Use a FocusNode when you need direct control over focus. The most common case is in forms, to move focus to the next TextField when the user submits the current one. It's also used for building custom keyboard navigation, accessibility features, or any scenario where you need to imperatively change which widget is active.

WHEN NOT TO USE IT: Avoid managing FocusNodes directly for simple cases. The Focus and FocusScope widgets handle the lifecycle automatically for many standard layouts. If you only need to know if a widget has focus during a build, calling Focus.of(context).hasFocus is often simpler and less error-prone than managing your own node. Direct management is powerful but adds complexity.

ONE CANONICAL EXAMPLE: A login form has two TextFields: one for email and one for password. You create two FocusNodes in initState, emailFocusNode and passwordFocusNode. The email TextField has focusNode: emailFocusNode and an onEditingComplete callback that calls passwordFocusNode.requestFocus(). When the user hits "done" on the keyboard in the email field, focus automatically jumps to the password field. Remember to dispose() both nodes in the State's dispose method.