FocusNavigator class

Manages focus navigation (with optional per-item error tracking) for views where every item is already visible.

When to use

Choose FocusNavigator when you have a finite list of focusable items on screen at once—forms, multi-step wizards, setting pages, command palettes, onboarding questionnaires, etc. It is intentionally simpler than ListNavigator because there is no viewport math to keep in sync.

Highlights

Index-based API that plugs nicely into your own data structures
Built-in wrapping so keyboard navigation feels natural
Optional validation helpers so UI can jump to the first invalid control
Cheap updates when the number of focusable widgets changes
Works great together with SelectionController and key handlers

Usage

final focus = FocusNavigator(itemCount: fields.length);

// Navigate with wrapping
focus.moveBy(1);   // down/next (wraps at end)
focus.moveBy(-1);  // up/previous (wraps at start)

// Absolute jumps
focus.jumpTo(3);
focus.jumpToLast();

// Track errors
focus.setError(2, 'Field is required');
if (focus.hasAnyError) {
  focus.focusFirstError(); // focus jumps to first invalid item
}

// Rendering loop
for (var i = 0; i < items.length; i++) {
  final isFocused = focus.isFocused(i);
  final error = focus.getError(i);
  // render item with focus indicator + error badge
}

Validation workflow

Wire up validation once and reuse it everywhere:

final allValid = focus.validateAll(
  (index) => values[index].isEmpty ? 'Required' : null,
  focusFirstInvalid: true,
);
if (allValid) submit();

By centralizing navigation state you avoid scattered int fields across widgets and make the API friendly for pub.dev consumers who just want a lightweight, well-documented helper.

Constructors

FocusNavigator({required int itemCount, int initialIndex = 0}): Creates a new focus navigation state.

Properties

errorCount → int: Number of items with errors.
no setter
firstErrorIndex → int?: Index of the first item with an error (null if none).
no setter
focusedError → String?: Error message for the focused item (null if no error).
no setter
focusedHasError → bool: Whether the focused item has an error.
no setter
focusedIndex → int: Current focused index.
no setter
hasAnyError → bool: Whether any item has an error.
no setter
hashCode → int: The hash code for this object.
no setterinherited
hasNoErrors → bool: Whether all items are error-free.
no setter
isEmpty → bool: Whether there are no items.
no setter
isNotEmpty → bool: Whether there are items.
no setter
itemCount ↔ int: Total number of items.
getter/setter pair
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

clearAllErrors() → void: Clears all errors.
clearError(int index) → void: Clears the error for an item.
focusFirstError() → bool: Focuses the first item with an error.
getError(int index) → String?: Gets the error message for an item (null if no error).
hasError(int index) → bool: Whether an item has an error.
isFocused(int index) → bool: Whether the given index is currently focused.
jumpTo(int index) → void: Jumps focus to a specific index (clamped to valid range).
jumpToFirst() → void: Jumps focus to the first item.
jumpToLast() → void: Jumps focus to the last item.
moveBy(int delta) → void: Moves focus by delta positions with wrapping.
moveDown() → void: Moves focus down by one (with wrapping).
moveNext() → void: Moves focus to next item (alias for moveDown).
movePrevious() → void: Moves focus to previous item (alias for moveUp).
moveUp() → void: Moves focus up by one (with wrapping).
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
reset({int initialIndex = 0, bool clearErrors = true}) → void: Resets focus to initial state (first item, clears all errors).
setError(int index, String? error) → void: Sets the error message for an item.
toString() → String: A string representation of this object.
inherited
validateAll(String? validator(int index), {bool focusFirstInvalid = true}) → bool: Validates all items using the provided validator function.
validateFocused(String? validator(int index)) → bool: Validates the focused item.
validateOne(int index, String? validator(int index)) → bool: Validates a single item using the provided validator function.

Operators

operator ==(Object other) → bool: The equality operator.
inherited