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 text or selection properties can be set from within a listener added to this controller. If both properties need to be changed then the controller's value should be set 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.
final _controller = TextEditingController();

void initState() {
  _controller.addListener(() {
    final text = _controller.text.toLowerCase();
    _controller.value = _controller.value.copyWith(
      text: text,
      selection: TextSelection(baseOffset: text.length, extentOffset: text.length),
      composing: TextRange.empty,
    );
  });
  super.initState();
}

void dispose() {
  _controller.dispose();
  super.dispose();
}

Widget build(BuildContext context) {
  return Scaffold(
    body: Container(
     alignment: Alignment.center,
      padding: const EdgeInsets.all(6),
      child: TextFormField(
        controller: _controller,
       decoration: InputDecoration(border: OutlineInputBorder()),
      ),
    ),
  );
}

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

selection TextSelection
The currently selected text. [...]
read / write
text String
The current string the user is editing.
read / write
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
value TextEditingValue
The current value stored in this notifier. [...]
read / write, inherited

Methods

clear() → void
Set the value to empty. [...]
clearComposing() → void
Set the composing region to an empty range. [...]
addListener(VoidCallback listener) → void
Register a closure to be called when the object changes. [...]
inherited
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
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed. [...]
inherited
notifyListeners() → void
Call all the registered listeners. [...]
@protected, @visibleForTesting, 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
Returns a string representation of this object.
inherited

Operators

operator ==(dynamic other) bool
The equality operator. [...]
inherited