TextEditingController class Null safety

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 or selection properties need to be changed, set the controller's value instead.

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.
To create a local project with this code sample, run:
flutter create --sample=widgets.TextEditingController.1 mysample

See also:

Inheritance

Constructors

TextEditingController({String? text})
Creates a controller for an editable text field. [...]
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. [...]
read-only, inherited
hasListeners bool
Whether any listeners are currently registered. [...]
@protected, read-only, inherited
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited
selection TextSelection
The currently selected text. [...]
read / write
text String
The current string the user is editing.
read / write
value TextEditingValue
The current value stored in this notifier. [...]
read / write, inherited-getter, override-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 and removeListener will throw after the object is disposed). [...]
@mustCallSuper, inherited
isSelectionWithinTextBounds(TextSelection selection) bool
Check that the selection is inside of the bounds of text.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed. [...]
inherited
notifyListeners() → void
Call all the registered listeners. [...]
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