FocusScope

A boundary for focus memory and optional focus trapping.

Learn more: Focus management

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

// Keep focus inside a custom overlay: Tab, clicks, and focus requests
// can't move it out.
FocusScope(
  trapFocus: true,
  // Stop unmatched keys from reaching the app behind it too.
  child: KeyBindings(modal: true, bindings: const [], child: child),
)

Details

Every scope remembers its most recently focused descendant. With trapFocus enabled, programmatic focus, pointer focus, and traversal are confined to this subtree. Key events may still propagate to ancestors; use KeyBindings(modal: true) when unmatched keys must also stop here.

Navigator routes install their own scope and traversal policy. Presented dialogs enable trapFocus and a key-binding boundary automatically.

Constructors

FocusScope()

Parameter	Type	Default	Description
trapFocus:	bool	false	Whether focus must stay inside this scope. More
child:	Widget	required	The subtree that shares this focus scope.

• trapFocus: When true, Tab and arrow traversal, pointer focus, and direct FocusNode.requestFocus calls cannot move focus outside this subtree. This does not stop key events from propagating to ancestor handlers.

Source

FocusScope is defined in packages/fleury/lib/src/widgets/focus.dart.

Category: Input handling & focus · All widgets

Live demo

focusscope_example.dart

Restart Run Expand

Example · editable Revert Format

class _FocusScopeExampleState extends State<_FocusScopeExample> {
  bool _trap = true;
  String _pressed = 'nothing yet';

  @override
  Widget build(BuildContext context) => Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      FocusScope(
        trapFocus: _trap,
        child: Container.framed(
          padding: const EdgeInsets.symmetric(horizontal: 1),
          child: Column(
            mainAxisSize: MainAxisSize.min,
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              Checkbox(
                value: _trap,
                label: 'Trap focus in this pane',
                autofocus: true,
                onChanged: (value) => setState(() => _trap = value),
              ),
              Row(
                children: [
                  Button(
                    text: 'Run',
                    onPressed: () => setState(() => _pressed = 'Run'),
                  ),
                  const SizedBox(width: 1),
                  Button(
                    text: 'Stop',
                    onPressed: () => setState(() => _pressed = 'Stop'),
                  ),
                ],
              ),
            ],
          ),
        ),
      ),
      Button(
        text: 'Outside',
        onPressed: () => setState(() => _pressed = 'Outside'),
      ),
      Text('pressed: $_pressed', style: const CellStyle(dim: true)),
    ],
  );
}

Live preview

Live · interactive

click & type to interact ⓘ how this demo runs ⛶ Expand