Document that programmatic TextEditingController changes do not run input formatters (#190166)
## Description
This PR documents that `TextInputFormatter`s are **not** run when a
`TextEditingController`'s value is changed programmatically.
The behavior is already [documented on
`EditableText`](https://github.com/flutter/flutter/blob/master/packages/flutter/lib/src/widgets/editable_text.dart#L611)
(formatters run on user input only), but `TextEditingController` itself
did not mention this. This has been a source of confusion for developers
who expect formatters to stay in sync with programmatic changes (see
#86354).
### Changes
- Added a paragraph to the `TextEditingController` class-level docs
explaining that input formatters only run when the user changes the text
(for example using the keyboard or the text selection menu), not when
the text is changed programmatically through the controller, and that
programmatically set values should be formatted manually if needed.
- Added a one-line note ("does not run `TextInputFormatter`s. See the
discussion at `TextEditingController`.") to the members that change the
value programmatically: the `value`, `text`, and `selection` setters,
`clear()`, and `clearComposing()`.
### Pre-launch Checklist
- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide].
- [x] I listed at least one issue that is owned by the Flutter team in
the description above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [ ] All existing and new tests are passing.
- [x] I signed the [CLA].
Fixes #86354
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/CONTRIBUTING.md
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/ A
Abdelrahman Saed committed
2e30b35d6915d06b6ad5ee5cab55fe3271a357c9
Parent: f72f5f4
Committed by GitHub <noreply@github.com>
on 8/21/2026, 6:21:18 AM