CupertinoTextField constructor

const CupertinoTextField({
  1. Key? key,
  2. Object groupId = EditableText,
  3. TextEditingController? controller,
  4. FocusNode? focusNode,
  5. UndoHistoryController? undoController,
  6. BoxDecoration? decoration = _kDefaultRoundedBorderDecoration,
  7. EdgeInsetsGeometry padding = const EdgeInsets.all(7.0),
  8. String? placeholder,
  9. TextStyle? placeholderStyle = const TextStyle(fontWeight: FontWeight.w400, color: CupertinoColors.placeholderText),
  10. Widget? prefix,
  11. OverlayVisibilityMode prefixMode = OverlayVisibilityMode.always,
  12. Widget? suffix,
  13. OverlayVisibilityMode suffixMode = OverlayVisibilityMode.always,
  14. OverlayVisibilityMode clearButtonMode = OverlayVisibilityMode.never,
  15. String? clearButtonSemanticLabel,
  16. TextInputType? keyboardType,
  17. TextInputAction? textInputAction,
  18. TextCapitalization textCapitalization = TextCapitalization.none,
  19. TextStyle? style,
  20. StrutStyle? strutStyle,
  21. TextAlign textAlign = TextAlign.start,
  22. TextAlignVertical? textAlignVertical,
  23. TextDirection? textDirection,
  24. bool readOnly = false,
  25. @Deprecated('Use `contextMenuBuilder` instead. ' 'This feature was deprecated after v3.3.0-0.5.pre.') ToolbarOptions? toolbarOptions,
  26. bool? showCursor,
  27. bool autofocus = false,
  28. String obscuringCharacter = '•',
  29. bool obscureText = false,
  30. bool autocorrect = true,
  31. SmartDashesType? smartDashesType,
  32. SmartQuotesType? smartQuotesType,
  33. bool enableSuggestions = true,
  34. int? maxLines = 1,
  35. int? minLines,
  36. bool expands = false,
  37. int? maxLength,
  38. MaxLengthEnforcement? maxLengthEnforcement,
  39. ValueChanged<String>? onChanged,
  40. VoidCallback? onEditingComplete,
  41. ValueChanged<String>? onSubmitted,
  42. TapRegionCallback? onTapOutside,
  43. List<TextInputFormatter>? inputFormatters,
  44. bool enabled = true,
  45. double cursorWidth = 2.0,
  46. double? cursorHeight,
  47. Radius cursorRadius = const Radius.circular(2.0),
  48. bool cursorOpacityAnimates = true,
  49. Color? cursorColor,
  50. BoxHeightStyle selectionHeightStyle = ui.BoxHeightStyle.tight,
  51. BoxWidthStyle selectionWidthStyle = ui.BoxWidthStyle.tight,
  52. Brightness? keyboardAppearance,
  53. EdgeInsets scrollPadding = const EdgeInsets.all(20.0),
  54. DragStartBehavior dragStartBehavior = DragStartBehavior.start,
  55. bool? enableInteractiveSelection,
  56. TextSelectionControls? selectionControls,
  57. GestureTapCallback? onTap,
  58. ScrollController? scrollController,
  59. ScrollPhysics? scrollPhysics,
  60. Iterable<String>? autofillHints = const <String>[],
  61. ContentInsertionConfiguration? contentInsertionConfiguration,
  62. Clip clipBehavior = Clip.hardEdge,
  63. String? restorationId,
  64. bool scribbleEnabled = true,
  65. bool enableIMEPersonalizedLearning = true,
  66. EditableTextContextMenuBuilder? contextMenuBuilder = _defaultContextMenuBuilder,
  67. SpellCheckConfiguration? spellCheckConfiguration,
  68. TextMagnifierConfiguration? magnifierConfiguration,
})

Creates an iOS-style text field.

To provide a prefilled text entry, pass in a TextEditingController with an initial value to the controller parameter.

To provide a hint placeholder text that appears when the text entry is empty, pass a String to the placeholder parameter.

The maxLines property can be set to null to remove the restriction on the number of lines. In this mode, the intrinsic height of the widget will grow as the number of lines of text grows. By default, it is 1, meaning this is a single-line text field and will scroll horizontally when it overflows. maxLines must not be zero.

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

If specified, the maxLength property must be greater than zero.

The selectionHeightStyle and selectionWidthStyle properties allow changing the shape of the selection highlighting. These properties default to ui.BoxHeightStyle.tight and ui.BoxWidthStyle.tight, respectively.

The autocorrect, autofocus, clearButtonMode, dragStartBehavior, expands, obscureText, prefixMode, readOnly, scrollPadding, suffixMode, textAlign, selectionHeightStyle, selectionWidthStyle, enableSuggestions, and enableIMEPersonalizedLearning properties must not be null.

Troubleshooting Common Accessibility Issues

Customizing User Input Accessibility Announcements

To customize user input accessibility announcements triggered by text changes, use SemanticsService.announce to make the desired accessibility announcement.

On iOS, the on-screen keyboard may announce the most recent input incorrectly when a TextInputFormatter inserts a thousands separator to a currency value text field. The following example demonstrates how to suppress the default accessibility announcements by always announcing the content of the text field as a US currency value (the \$ inserts a dollar sign, the $newText interpolates the newText variable):

onChanged: (String newText) {
  if (newText.isNotEmpty) {
    SemanticsService.announce('\$$newText', Directionality.of(context));
  }
}

See also:

  • minLines, which is the minimum number of lines to occupy when the content spans fewer lines.
  • expands, to allow the widget to size itself to its parent's height.
  • maxLength, which discusses the precise meaning of "number of characters" and how it may differ from the intuitive meaning.

Implementation

const CupertinoTextField({
  super.key,
  this.groupId = EditableText,
  this.controller,
  this.focusNode,
  this.undoController,
  this.decoration = _kDefaultRoundedBorderDecoration,
  this.padding = const EdgeInsets.all(7.0),
  this.placeholder,
  this.placeholderStyle = const TextStyle(
    fontWeight: FontWeight.w400,
    color: CupertinoColors.placeholderText,
  ),
  this.prefix,
  this.prefixMode = OverlayVisibilityMode.always,
  this.suffix,
  this.suffixMode = OverlayVisibilityMode.always,
  this.clearButtonMode = OverlayVisibilityMode.never,
  this.clearButtonSemanticLabel,
  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.obscuringCharacter = '•',
  this.obscureText = false,
  this.autocorrect = true,
  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.onTapOutside,
  this.inputFormatters,
  this.enabled = true,
  this.cursorWidth = 2.0,
  this.cursorHeight,
  this.cursorRadius = const Radius.circular(2.0),
  this.cursorOpacityAnimates = true,
  this.cursorColor,
  this.selectionHeightStyle = ui.BoxHeightStyle.tight,
  this.selectionWidthStyle = ui.BoxWidthStyle.tight,
  this.keyboardAppearance,
  this.scrollPadding = const EdgeInsets.all(20.0),
  this.dragStartBehavior = DragStartBehavior.start,
  bool? enableInteractiveSelection,
  this.selectionControls,
  this.onTap,
  this.scrollController,
  this.scrollPhysics,
  this.autofillHints = const <String>[],
  this.contentInsertionConfiguration,
  this.clipBehavior = Clip.hardEdge,
  this.restorationId,
  this.scribbleEnabled = true,
  this.enableIMEPersonalizedLearning = true,
  this.contextMenuBuilder = _defaultContextMenuBuilder,
  this.spellCheckConfiguration,
  this.magnifierConfiguration,
}) : 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 > 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);