Flutter: TextField difference between onEdittingComplete and onSubmitted

Question

I am trying to figure out the difference between onEdittingComplete and onSubmitted, I don't know when the latter should be used since the former can be used to switch focus or to submit the content of the form.

I tried looking into the documentation but there is not much said about the onSubmitted property.

Tiffanitiffanie

Answer 1

onSubmitted

As the name suggestions, it's called when user finishes editing, e.g. press "done" or "send" on the keyboard. The callback conveniently passes the value to you, so you can do your business logic with it. At the same time, since Flutter assumes the user is "done", it will hide the on-screen keyboard.

onEditingComplete

This is more of an "FYI" that tells you that the user has finished editing. It is fired before onSubmitted. It does not pass you the value (while you can technically get the value using a controller, that's not the intention here), because you can still handle value-related business logic in onSubmitted. Both events will fire anyway.

The real purpose behind onEditingComplete is that, in the default implementation, Flutter hides the on-screen keyboard when the keyboard action is considered a "completion action", such as "done", "go", "send", or "search", but does not hide the keyboard if the action is "non-completion", such as "next" or "previous". (The keyboard action is specified in TextField widget's textInputAction property.)

If you don't like this behaviour, you can override it. For example, "send" is considered a "completion action" here, thus in an Instant Messaging (chatting) app, each time user sends a short message, the keyboard will be collapsed, that's not good. But if we override the onEditingComplete callback to an empty function, it will stop the default behaviour and not hide the keyboard. For example:

TextField(
  controller: _controller,
  onSubmitted: (text) {
    sendMessage(text);
    _controller.clear();
  },
  onEditingComplete: () {}, // do not hide keyboard
  textInputAction: TextInputAction.send,
)

Demo:

Mettle

there is also the onFieldSubmitted property – Alisun

@Alisun it's the same thing, api.flutter.dev/flutter/material/TextFormField/… – Xanthous

Answer 2

onSubmitted:

final ValueChanged<String> onSubmitted

It returns the TextField entered value in onSubmitted callback, most of the time its used for next/previous field button of keyboard when using TextInputAction.next and TextInputAction.previous for textInputAction performed.

onEditingComplete:

final VoidCallback onEditingComplete

It's similar to onSubmitted but does not return value inside the callback, instead, it updates the text controller and then we can fetch a value from the controller where ever required.

Agamic

instead, it updates the text controller isn't the controller auto-updated each time a character is entered or deleted? – Tiffanitiffanie

I think textController do that, but onEditingComplete is some sort of callback mechanism which tell us that text editing is done and now we can use that value. – Agamic

Answer 3

For mobile, onEditingComplete is called before the keyboard closes and onSubmitted is called after.

Strained