TextInput class

A single-line editable text field. Read or set its text through a TextEditingController, or react to edits with onChanged and onSubmit.

While focused, the field takes typed characters, so a binding in an enclosing KeyBindings whose first key is one, such as q, doesn't fire. A typed character that continues a sequence already under way still reaches its binding: the b of Ctrl+X b completes it. Other keys the field doesn't use, such as Ctrl+S, pass on to enclosing widgets. With the default keymap (TextEditingKeymap.defaultSingleLine):

  • Left and Right move the caret. At either end of the text, with nothing selected, an unmodified press passes on instead, so arrow-key focus traversal can move on. Ctrl+Left and Ctrl+Right (or Alt+Left and Alt+Right) move by word, and Home and End jump to the start and end. Add Shift to any of these to extend the selection.
  • Backspace and Delete delete a character; Ctrl+Backspace or Alt+Backspace deletes the word before the caret.
  • Ctrl+A selects all. Ctrl+C copies and Ctrl+X cuts the selection; with nothing selected they pass on, so an unhandled Ctrl+C still quits a terminal app.
  • Ctrl+Z undoes. The field consumes Ctrl+Z even with nothing to undo, so a terminal app doesn't suspend on it while the field has focus. Ctrl+Y redoes, as does Ctrl+Shift+Z where the terminal can report it.
  • Up and Down move through an open completion list (see completionController); without one, they step through historyController's entries. Otherwise they pass on.
  • Tab accepts the selected completion; without an open completion list, it passes on.
  • Enter calls onSubmit. The field consumes Enter even when onSubmit is null.
  • Escape closes an open completion list; otherwise it calls onEscape, or passes on when onEscape is null.

Where the terminal or browser reports the Super key (Cmd on macOS), Super+A, Super+C, Super+X, Super+Z, and Super+Shift+Z do the same as their Ctrl forms. TextEditingKeymap.emacsSingleLine adds Emacs-style keys and takes over Ctrl+A and Ctrl+Y: among others, Ctrl+A and Ctrl+E jump to the start and end; Ctrl+K, Ctrl+U, and Ctrl+W cut text into a kill ring shared by all fields; and Ctrl+Y pastes it back.

Unless the controller opts into preserving text, input is canonicalized before it reaches the model: control bytes are replaced and escape sequences are collapsed, so the field's content is exactly what it draws. See TextEditingController for the rules and what an app reads back.

Inheritance
Available extensions

Constructors

TextInput({Key? key, TextEditingController? controller, FocusNode? focusNode, bool autofocus = false, void onChanged(String text)?, void onSubmit(String text)?, void onEscape()?, String placeholder = '', CellStyle placeholderStyle = const CellStyle(dim: true), CellStyle style = CellStyle.none, CellStyle cursorStyle = const CellStyle(inverse: true), Duration blinkInterval = const Duration(milliseconds: 500), bool enableBlink = true, bool obscureText = false, String obscuringCharacter = '•', bool enabled = true, bool readOnly = false, String? validationError, String? semanticLabel, SemanticState semanticState = SemanticState.empty, TextClipboardPolicy? clipboardPolicy, TextHistoryController? historyController, bool commitHistoryOnSubmit = true, TextCompletionController? completionController, void onCompletionAccepted(TextCompletionOption option)?, TextEditingKeymap keymap = TextEditingKeymap.defaultSingleLine, TextPastePolicy pastePolicy = const TextPastePolicy()})
const

Properties

autofocus → bool
Whether to request focus on first mount.
final
blinkInterval → Duration
On/off cadence for the blinking cursor. Default matches native terminal conventions (~500 ms).
final
clipboardPolicy → TextClipboardPolicy?
How copy, cut, and the kill ring treat this field's text. Null (the default) means TextClipboardPolicy.redacted when obscureText is true and TextClipboardPolicy.allowed otherwise.
final
commitHistoryOnSubmit → bool
Whether Enter adds the submitted text to historyController before calling onSubmit. Has no effect when onSubmit is null.
final
completionController → TextCompletionController?
Completion state for this field: while its list is open, Up and Down move the selected option, Tab accepts it, and Escape closes the list.
final
controller → TextEditingController?
External controller for the text. If null, the widget creates its own and disposes it on unmount.
final
cursorStyle → CellStyle
Style merged on top of style at the cursor cell. Defaults to inverse: true — a block cursor.
final
When true (default), the cursor blinks while the widget is focused. When false, the cursor is rendered solid whenever the widget is focused. The cursor is always suppressed when the widget is unfocused.
final
enabled → bool
Whether the field can receive focus and handle input.
final
focusNode → FocusNode?
External FocusNode. Provide one when a parent needs to drive focus (e.g. Tab cycling between panes). If null, the widget creates its own and disposes it on unmount.
final
hashCode → int
The hash code for this object.
no setterinherited
historyController → TextHistoryController?
Optional command/submission history for Up/Down navigation.
final
key → Key?
finalinherited
keymap → TextEditingKeymap
Which keys trigger which editing actions. Defaults to TextEditingKeymap.defaultSingleLine; TextEditingKeymap.emacsSingleLine adds Emacs-style keys such as Ctrl+A, Ctrl+E, and Ctrl+K.
final
obscureText → bool
When true, each grapheme of the field's text is replaced with obscuringCharacter at paint time. The controller still holds the real text — only the displayed glyphs are masked. Use for password / secret entry.
final
obscuringCharacter → String
The glyph used to replace each character when obscureText is true. Defaults to •.
final
onChanged → void Function(String text)?
Called after typing, deletion, paste, history navigation, completion, or a semantic edit changes the text. Programmatic controller writes do not call this; use controller listeners to observe changes from any origin. Cursor-only moves and rejected edits do not call this callback.
final
onCompletionAccepted → void Function(TextCompletionOption option)?
Called after a selected completion option is applied.
final
onEscape → void Function()?
Called when the user presses Escape while no completion list is open (Escape closes an open one first). If null, Escape passes on to enclosing widgets.
final
onSubmit → void Function(String text)?
Called with the current text when the user presses Enter. The field consumes Enter even when this is null.
final
pastePolicy → TextPastePolicy
Policy for chunking large bracketed paste payloads.
final
placeholder → String
Hint text shown when the field is empty. Cleared as soon as the user types.
final
placeholderStyle → CellStyle
Style for the placeholder text. Defaults to dim.
final
readOnly → bool
Whether the field can receive focus but refuses text mutations.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
semanticLabel → String?
Label exposed through the semantic app graph.
final
semanticState → SemanticState
Extra semantic state merged into the text-field node.
final
style → CellStyle
Style for the rendered text and its interactive states.
final
validationError → String?
Validation error attached directly to this input's current value.
final

Methods

animate({Duration? duration, Curve? curve, Object? trigger, bool repeat = false}) → Animate

Available on Widget, provided by the AnimateExtension extension

Starts an Animate chain over this widget. duration / curve apply to the whole chain. With no trigger it plays on mount; with a non-null trigger it rests on mount and replays whenever the token changes.
createElement() → StatefulElement
Creates the Element that will mount this widget into the tree.
inherited
createState() → State<TextInput>
Creates the mutable state for this widget at the current location in the tree. Called exactly once per StatefulElement instance.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

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