EditableText class

A basic text input field.

This widget interacts with the TextInput service to let the user edit the text it contains. It also provides scrolling, selection, and cursor movement.

The EditableText widget is a low-level widget that is intended as a building block for custom widget sets. For a complete user experience, consider using a TextField or CupertinoTextField.

Handling User Input

Currently the user may change the text this widget contains via keyboard or the text selection menu. When the user inserted or deleted text, you will be notified of the change and get a chance to modify the new text value:

• The inputFormatters will be first applied to the user input.

• The controller's TextEditingController.value will be updated with the formatted result, and the controller's listeners will be notified.

• The onChanged callback, if specified, will be called last.

Input Actions

A TextInputAction can be provided to customize the appearance of the action button on the soft keyboard for Android and iOS. The default action is TextInputAction.done.

Many TextInputActions are common between Android and iOS. However, if a textInputAction is provided that is not supported by the current platform in debug mode, an error will be thrown when the corresponding EditableText receives focus. For example, providing iOS's "emergencyCall" action when running on an Android device will result in an error when in debug mode. In release mode, incompatible TextInputActions are replaced either with "unspecified" on Android, or "default" on iOS. Appropriate textInputActions can be chosen by checking the current platform and then selecting the appropriate action.

Lifecycle

Upon completion of editing, like pressing the "done" button on the keyboard, two actions take place:

1st: Editing is finalized. The default behavior of this step includes an invocation of onChanged. That default behavior can be overridden. See onEditingComplete for details.

2nd: onSubmitted is invoked with the user's input value.

onSubmitted can be used to manually move focus to another input widget when a user finishes with the currently focused input widget.

When the widget has focus, it will prevent itself from disposing via AutomaticKeepAliveClientMixin.wantKeepAlive in order to avoid losing the selection. Removing the focus will allow it to be disposed.

Rather than using this widget directly, consider using TextField, which is a full-featured, material-design text input field with placeholder text, labels, and Form integration.

Text Editing Intents and Their Default Actions

This widget provides default Actions for handling common text editing Intents such as deleting, copying and pasting in the text field. These Actions can be directly invoked using Actions.invoke or the Actions.maybeInvoke method. The default text editing keyboard Shortcuts, typically declared in DefaultTextEditingShortcuts, also use these Intents and Actions to perform the text editing operations they are bound to.

The default handling of a specific Intent can be overridden by placing an Actions widget above this widget. See the Action class and the Action.overridable constructor for more information on how a pre-defined overridable Action can be overridden.

Intents for Deleting Text and Their Default Behavior

Intents for Moving the Caret

Intents for Extending the Selection

Other Intents

Text Editing Shortcuts

It's also possible to directly remap keyboard shortcuts to new Intents by inserting a Shortcuts widget above this in the widget tree. When using WidgetsApp, the large set of default text editing keyboard shortcuts are declared near the top of the widget tree in DefaultTextEditingShortcuts, and any Shortcuts widget between it and this EditableText will override those defaults.

Interactions Between Shortcuts and Text Input

Shortcuts prevent text input fields from receiving their keystrokes as text input. For example, placing a Shortcuts widget in the widget tree above a text input field and creating a shortcut for LogicalKeyboardKey.keyA will prevent the field from receiving that key as text input. In other words, typing key "A" into the field will trigger the shortcut and will not insert a letter "a" into the field.

This happens because of the way that key strokes are handled in Flutter. When a keystroke is received in Flutter's engine, it first gives the framework the opportunity to handle it as a raw key event through SystemChannels.keyEvent. This is what Shortcuts listens to indirectly through its FocusNode. If it is not handled, then it will proceed to try handling it as text input through SystemChannels.textInput, which is what EditableTextState listens to through TextInputClient.

This behavior, where a shortcut prevents text input into some field, can be overridden by using another Shortcuts widget lower in the widget tree and mapping the desired key stroke(s) to DoNothingAndStopPropagationIntent. The key event will be reported as unhandled by the framework and will then be sent as text input as usual.

Gesture Events Handling

When rendererIgnoresPointer is false (the default), this widget provides rudimentary, platform-agnostic gesture handling for user actions such as tapping, long-pressing, and scrolling.

To provide more complete gesture handling, including double-click to select a word, drag selection, and platform-specific handling of gestures such as long presses, consider setting rendererIgnoresPointer to true and using TextSelectionGestureDetectorBuilder.

Keep the caret visible when focused

When focused, this widget will make attempts to keep the text area and its caret (even when showCursor is false) visible, on these occasions:

• When the user focuses this text field and it is not readOnly.
• When the user changes the selection of the text field, or changes the text when the text field is not readOnly.
• When the virtual keyboard pops up.

Scrolling Considerations

If this EditableText is not a descendant of Scaffold and is being used within a Scrollable or nested Scrollables, consider placing a ScrollNotificationObserver above the root Scrollable that contains this EditableText to ensure proper scroll coordination for EditableText and its components like TextSelectionOverlay.

Troubleshooting Common Accessibility Issues

Customizing User Input Accessibility Announcements

To customize user input accessibility announcements triggered by text changes, use SemanticsService.announce to make the desired accessibility announcement.

On iOS, the on-screen keyboard may announce the most recent input incorrectly when a TextInputFormatter inserts a thousands separator to a currency value text field. The following example demonstrates how to suppress the default accessibility announcements by always announcing the content of the text field as a US currency value (the \$ inserts a dollar sign, the $newText interpolates the newText variable):

onChanged: (String newText) {
  if (newText.isNotEmpty) {
    SemanticsService.announce('\$$newText', Directionality.of(context));
  }
}

See also:

• TextField, which is a full-featured, material-design text input field with placeholder text, labels, and Form integration.