FocusScope class

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, FocusNode? parentNode, 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.
FocusScope.withExternalFocusNode({Key? key, required Widget child, required FocusScopeNode focusScopeNode, FocusNode? parentNode, bool autofocus, ValueChanged<bool>? onFocusChange})
Creates a FocusScope widget that uses the given focusScopeNode as the source of truth for attributes on the node, rather than the attributes of this widget.


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


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.
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent 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.

Static Methods

of(BuildContext context, {bool createDependency = true}) FocusScopeNode
Returns the FocusNode.nearestScope of the Focus or FocusScope that most tightly encloses the given context.