TextField constructor

const TextField({
  1. Key? key,
  2. Object groupId = EditableText,
  3. TextEditingController? controller,
  4. FocusNode? focusNode,
  5. UndoHistoryController? undoController,
  6. InputDecoration? decoration = const InputDecoration(),
  7. TextInputType? keyboardType,
  8. TextInputAction? textInputAction,
  9. TextCapitalization textCapitalization = TextCapitalization.none,
  10. TextStyle? style,
  11. StrutStyle? strutStyle,
  12. TextAlign textAlign = TextAlign.start,
  13. TextAlignVertical? textAlignVertical,
  14. TextDirection? textDirection,
  15. bool readOnly = false,
  16. @Deprecated('Use `contextMenuBuilder` instead. ' 'This feature was deprecated after v3.3.0-0.5.pre.') ToolbarOptions? toolbarOptions,
  17. bool? showCursor,
  18. bool autofocus = false,
  19. MaterialStatesController? statesController,
  20. String obscuringCharacter = '•',
  21. bool obscureText = false,
  22. bool? autocorrect,
  23. SmartDashesType? smartDashesType,
  24. SmartQuotesType? smartQuotesType,
  25. bool enableSuggestions = true,
  26. int? maxLines = 1,
  27. int? minLines,
  28. bool expands = false,
  29. int? maxLength,
  30. MaxLengthEnforcement? maxLengthEnforcement,
  31. ValueChanged<String>? onChanged,
  32. VoidCallback? onEditingComplete,
  33. ValueChanged<String>? onSubmitted,
  34. AppPrivateCommandCallback? onAppPrivateCommand,
  35. List<TextInputFormatter>? inputFormatters,
  36. bool? enabled,
  37. bool? ignorePointers,
  38. double cursorWidth = 2.0,
  39. double? cursorHeight,
  40. Radius? cursorRadius,
  41. bool? cursorOpacityAnimates,
  42. Color? cursorColor,
  43. Color? cursorErrorColor,
  44. BoxHeightStyle? selectionHeightStyle,
  45. BoxWidthStyle? selectionWidthStyle,
  46. Brightness? keyboardAppearance,
  47. EdgeInsets scrollPadding = const EdgeInsets.all(20.0),
  48. DragStartBehavior dragStartBehavior = DragStartBehavior.start,
  49. bool? enableInteractiveSelection,
  50. bool? selectAllOnFocus,
  51. TextSelectionControls? selectionControls,
  52. GestureTapCallback? onTap,
  53. bool onTapAlwaysCalled = false,
  54. TapRegionCallback? onTapOutside,
  55. TapRegionUpCallback? onTapUpOutside,
  56. MouseCursor? mouseCursor,
  57. InputCounterWidgetBuilder? buildCounter,
  58. ScrollController? scrollController,
  59. ScrollPhysics? scrollPhysics,
  60. Iterable<String>? autofillHints = const <String>[],
  61. ContentInsertionConfiguration? contentInsertionConfiguration,
  62. Clip clipBehavior = Clip.hardEdge,
  63. String? restorationId,
  64. @Deprecated('Use `stylusHandwritingEnabled` instead. ' 'This feature was deprecated after v3.27.0-0.2.pre.') bool scribbleEnabled = true,
  65. bool stylusHandwritingEnabled = EditableText.defaultStylusHandwritingEnabled,
  66. bool enableIMEPersonalizedLearning = true,
  67. EditableTextContextMenuBuilder? contextMenuBuilder = _defaultContextMenuBuilder,
  68. bool canRequestFocus = true,
  69. SpellCheckConfiguration? spellCheckConfiguration,
  70. TextMagnifierConfiguration? magnifierConfiguration,
  71. List<Locale>? hintLocales,
})

Creates a Material Design text field.

If decoration is non-null (which is the default), the text field requires one of its ancestors to be a Material widget.

To remove the decoration entirely (including the extra padding introduced by the decoration to save space for the labels), set the decoration to null.

The maxLines property can be set to null to remove the restriction on the number of lines. By default, it is one, meaning this is a single-line text field. maxLines must not be zero.

The maxLength property is set to null by default, which means the number of characters allowed in the text field is not restricted. If maxLength is set a character counter will be displayed below the field showing how many characters have been entered. If the value is set to a positive integer it will also display the maximum allowed number of characters to be entered. If the value is set to TextField.noMaxLength then only the current length is displayed.

After maxLength characters have been input, additional input is ignored, unless maxLengthEnforcement is set to MaxLengthEnforcement.none. The text field enforces the length with a LengthLimitingTextInputFormatter, which is evaluated after the supplied inputFormatters, if any. The maxLength value must be either null or greater than zero.

If maxLengthEnforcement is set to MaxLengthEnforcement.none, then more than maxLength characters may be entered, and the error counter and divider will switch to the decoration.errorStyle when the limit is exceeded.

The text cursor is not shown if showCursor is false or if showCursor is null (the default) and readOnly is true.

The selectionHeightStyle and selectionWidthStyle properties allow changing the shape of the selection highlighting. These properties default to EditableText.defaultSelectionHeightStyle and EditableText.defaultSelectionHeightStyle, respectively.

See also:

  • maxLength, which discusses the precise meaning of "number of characters" and how it may differ from the intuitive meaning.

Implementation

const TextField({
  super.key,
  this.groupId = EditableText,
  this.controller,
  this.focusNode,
  this.undoController,
  this.decoration = const InputDecoration(),
  TextInputType? keyboardType,
  this.textInputAction,
  this.textCapitalization = TextCapitalization.none,
  this.style,
  this.strutStyle,
  this.textAlign = TextAlign.start,
  this.textAlignVertical,
  this.textDirection,
  this.readOnly = false,
  @Deprecated(
    'Use `contextMenuBuilder` instead. '
    'This feature was deprecated after v3.3.0-0.5.pre.',
  )
  this.toolbarOptions,
  this.showCursor,
  this.autofocus = false,
  this.statesController,
  this.obscuringCharacter = '•',
  this.obscureText = false,
  this.autocorrect,
  SmartDashesType? smartDashesType,
  SmartQuotesType? smartQuotesType,
  this.enableSuggestions = true,
  this.maxLines = 1,
  this.minLines,
  this.expands = false,
  this.maxLength,
  this.maxLengthEnforcement,
  this.onChanged,
  this.onEditingComplete,
  this.onSubmitted,
  this.onAppPrivateCommand,
  this.inputFormatters,
  this.enabled,
  this.ignorePointers,
  this.cursorWidth = 2.0,
  this.cursorHeight,
  this.cursorRadius,
  this.cursorOpacityAnimates,
  this.cursorColor,
  this.cursorErrorColor,
  this.selectionHeightStyle,
  this.selectionWidthStyle,
  this.keyboardAppearance,
  this.scrollPadding = const EdgeInsets.all(20.0),
  this.dragStartBehavior = DragStartBehavior.start,
  bool? enableInteractiveSelection,
  this.selectAllOnFocus,
  this.selectionControls,
  this.onTap,
  this.onTapAlwaysCalled = false,
  this.onTapOutside,
  this.onTapUpOutside,
  this.mouseCursor,
  this.buildCounter,
  this.scrollController,
  this.scrollPhysics,
  this.autofillHints = const <String>[],
  this.contentInsertionConfiguration,
  this.clipBehavior = Clip.hardEdge,
  this.restorationId,
  @Deprecated(
    'Use `stylusHandwritingEnabled` instead. '
    'This feature was deprecated after v3.27.0-0.2.pre.',
  )
  this.scribbleEnabled = true,
  this.stylusHandwritingEnabled = EditableText.defaultStylusHandwritingEnabled,
  this.enableIMEPersonalizedLearning = true,
  this.contextMenuBuilder = _defaultContextMenuBuilder,
  this.canRequestFocus = true,
  this.spellCheckConfiguration,
  this.magnifierConfiguration,
  this.hintLocales,
}) : assert(obscuringCharacter.length == 1),
     smartDashesType =
         smartDashesType ?? (obscureText ? SmartDashesType.disabled : SmartDashesType.enabled),
     smartQuotesType =
         smartQuotesType ?? (obscureText ? SmartQuotesType.disabled : SmartQuotesType.enabled),
     assert(maxLines == null || maxLines > 0),
     assert(minLines == null || minLines > 0),
     assert(
       (maxLines == null) || (minLines == null) || (maxLines >= minLines),
       "minLines can't be greater than maxLines",
     ),
     assert(
       !expands || (maxLines == null && minLines == null),
       'minLines and maxLines must be null when expands is true.',
     ),
     assert(!obscureText || maxLines == 1, 'Obscured fields cannot be multiline.'),
     assert(maxLength == null || maxLength == TextField.noMaxLength || maxLength > 0),
     // Assert the following instead of setting it directly to avoid surprising the user by silently changing the value they set.
     assert(
       !identical(textInputAction, TextInputAction.newline) ||
           maxLines == 1 ||
           !identical(keyboardType, TextInputType.text),
       'Use keyboardType TextInputType.multiline when using TextInputAction.newline on a multiline TextField.',
     ),
     keyboardType =
         keyboardType ?? (maxLines == 1 ? TextInputType.text : TextInputType.multiline),
     enableInteractiveSelection = enableInteractiveSelection ?? (!readOnly || !obscureText);