TextEditingController class

A controller for an editable text field.

Whenever the user modifies a text field with an associated TextEditingController, the text field updates value and the controller notifies its listeners. Listeners can then read the text and selection properties to learn what the user has typed or how the selection has been updated.

Similarly, if you modify the text or selection properties, the text field will be notified and will update itself appropriately.

A TextEditingController can also be used to provide an initial value for a text field. If you build a text field with a controller that already has text, the text field will use that text as its initial value.

The value (as well as text and selection) of this controller can be updated from within a listener added to this controller. Be aware of infinite loops since the listener will also be notified of the changes made from within itself. Modifying the composing region from within a listener can also have a bad interaction with some input methods. Gboard, for example, will try to restore the composing region of the text if it was modified programmatically, creating an infinite loop of communications between the framework and the input method. Consider using TextInputFormatters instead for as-you-type text modification.

If both the text and selection properties need to be changed, set the controller's value instead. Setting text will clear the selection and composing range.

Remember to dispose of the TextEditingController when it is no longer needed. This will ensure we discard any resources used by the object.

This example creates a TextField with a TextEditingController whose change listener forces the entered text to be lower case and keeps the cursor at the end of the input.
link

To create a local project with this code sample, run:
flutter create --sample=widgets.TextEditingController.1 mysample

See also:

Inheritance
Implementers

Constructors

TextEditingController({String? text})
Creates a controller for an editable text field, with no initial selection.
TextEditingController.fromValue(TextEditingValue? value)
Creates a controller for an editable text field from an initial TextEditingValue.

Properties

hashCode int
The hash code for this object.
no setterinherited
hasListeners bool
Whether any listeners are currently registered.
no setterinherited
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
selection TextSelection
The currently selected range within text.
getter/setter pair
text String
The current string the user is editing.
getter/setter pair
value TextEditingValue
The current value stored in this notifier.
getter/setter pairinherited-getteroverride-setter

Methods

addListener(VoidCallback listener) → void
Register a closure to be called when the object changes.
inherited
buildTextSpan({required BuildContext context, TextStyle? style, required bool withComposing}) TextSpan
Builds TextSpan from current editing value.
clear() → void
Set the value to empty.
clearComposing() → void
Set the composing region to an empty range.
dispose() → void
Discards any resources used by the object. After this is called, the object is not in a usable state and should be discarded (calls to addListener will throw after the object is disposed).
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void
Call all the registered listeners.
inherited
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
toString() String
A string representation of this object.
inherited

Operators

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