FocusScope class Null safety

A FocusScope is similar to a Focus, but also serves as a scope for its descendants, restricting focus traversal to the scoped controls.

For example a new FocusScope is created automatically when a route is pushed, keeping the focus traversal from moving to a control in a previous route.

If you just want to group widgets together in a group so that they are traversed in a particular order, but the focus can still leave the group, use a FocusTraversalGroup.

Like Focus, FocusScope provides an onFocusChange as a way to be notified when the focus is given to or removed from this widget.

The onKey argument allows specification of a key event handler that is invoked when this node or one of its children has focus. Keys are handed to the primary focused widget first, and then they propagate through the ancestors of that node, stopping if one of them returns KeyEventResult.handled from onKey, indicating that it has handled the event.

Managing a FocusScopeNode means managing its lifecycle, listening for changes in focus, and re-parenting it when needed to keep the focus hierarchy in sync with the widget hierarchy. This widget does all of those things for you. See FocusScopeNode for more information about the details of what node management entails if you are not using a FocusScope widget and you need to do it yourself.

FocusScopeNodes remember the last FocusNode that was focused within their descendants, and can move that focus to the next/previous node, or a node in a particular direction when the FocusNode.nextFocus, FocusNode.previousFocus, or FocusNode.focusInDirection are called on a FocusNode or FocusScopeNode.

To move the focus, use methods on FocusNode by getting the FocusNode through the of method. For instance, to move the focus to the next node in the focus traversal order, call Focus.of(context).nextFocus(). To unfocus a widget, call Focus.of(context).unfocus().

This example demonstrates using a FocusScope to restrict focus to a particular portion of the app. In this case, restricting focus to the visible part of a Stack.
To create a local project with this code sample, run:
flutter create --sample=widgets.FocusScope.1 mysample

See also:

  • FocusScopeNode, which represents a scope node in the focus hierarchy.
  • FocusNode, which represents a node in the focus hierarchy and has an explanation of the focus system.
  • Focus, a widget that manages a FocusNode and allows easy access to managing focus without having to manage the node.
  • FocusManager, a singleton that manages the focus and distributes key events to focused nodes.
  • FocusTraversalPolicy, an object used to determine how to move the focus to other nodes.
  • FocusTraversalGroup, a widget used to configure the focus traversal policy for a widget subtree.


FocusScope({Key? key, FocusScopeNode? node, required Widget child, bool autofocus = false, ValueChanged<bool>? onFocusChange, bool? canRequestFocus, bool? skipTraversal, FocusOnKeyEventCallback? onKeyEvent, FocusOnKeyCallback? onKey, String? debugLabel})
Creates a widget that manages a FocusScopeNode. [...]


autofocus bool
True if this widget will be selected as the initial focus when no other node in its scope is currently focused. [...]
final, inherited
canRequestFocus bool?
If true, this widget may request the primary focus. [...]
final, inherited
child Widget
The child widget of this Focus. [...]
final, inherited
debugLabel String?
A debug label for this widget. [...]
final, inherited
descendantsAreFocusable bool
If false, will make this widget's descendants unfocusable. [...]
final, inherited
focusNode FocusNode?
An optional focus node to use as the focus node for this widget. [...]
final, inherited
hashCode int
The hash code for this object. [...]
@nonVirtual, read-only, inherited
includeSemantics bool
Include semantics information in this widget. [...]
final, inherited
key Key?
Controls how one widget replaces another widget in the tree. [...]
final, inherited
onFocusChange ValueChanged<bool>?
Handler called when the focus changes. [...]
final, inherited
onKey FocusOnKeyCallback?
Handler for keys pressed when this object or one of its children has focus. [...]
final, inherited
onKeyEvent FocusOnKeyEventCallback?
Handler for keys pressed when this object or one of its children has focus. [...]
final, inherited
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited
skipTraversal bool?
Sets the FocusNode.skipTraversal flag on the focus node so that it won't be visited by the FocusTraversalPolicy. [...]
final, inherited


createElement() StatefulElement
Creates a StatefulElement to manage this widget's location in the tree. [...]
createState() State<Focus>
Creates the mutable state for this widget at a given location in the tree. [...]
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children. [...]
@protected, inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node. [...]
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed. [...]
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep. [...]
toString({DiagnosticLevel minLevel =}) String
A string representation of this object. [...]
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a string representation of this node and its descendants. [...]
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a one-line detailed description of the object. [...]
toStringShort() String
A short, textual description of this widget.


operator ==(Object other) bool
The equality operator. [...]
@nonVirtual, inherited

Static Methods

of(BuildContext context) FocusScopeNode
Returns the FocusScopeNode of the FocusScope that most tightly encloses the given context. [...]