Use maxLengthEnforcement instead of maxLengthEnforced

Using the default behavior for the current platform is recommended, since this will be the behavior most familiar to the user.

Default values of maxLengthEnforcement

• Android, Windows: MaxLengthEnforcement.enforced. The native behavior of these platforms is enforced. The inputting value will be truncated whether the user is entering with composition or not.
• iOS, macOS: MaxLengthEnforcement.truncateAfterCompositionEnds. These platforms do not have a "maximum length" feature and therefore require that developers implement the behavior themselves. No standard convention seems to have evolved on these platforms. We have chosen to allow the composition to exceed the maximum length to avoid breaking CJK input.
• Web and Linux: MaxLengthEnforcement.truncateAfterCompositionEnds. While there is no standard on these platforms (and many implementation exist with conflicting behavior), the common convention seems to be to allow the composition to exceed the maximum length by default.
• Fuchsia: MaxLengthEnforcement.truncateAfterCompositionEnds. There is no platform convention on this platform yet, so we have chosen to default to the convention that is least likely to result in data loss.

To enforce the limit all the time

To enforce the limit that always truncate the value when it reaches the limit (for example, when entering a verification code), use MaxLengthEnforcement.enforced in editable text fields.

This option may give suboptimal user experience when used with input methods that rely on text composition. Consider using the truncateAfterCompositionEnds option when the text field expects arbitrary user input which may contain CJK characters. See the Context section for more information.

Code before migration:

TextField(maxLength: 6)

or:

TextField(
  maxLength: 6,
  maxLengthEnforced: true,
)

Code after migration:

TextField(
  maxLength: 6,
  maxLengthEnforcement: MaxLengthEnforcement.enforced,
)

To not enforce the limitation

To show a max length error in TextField, but not truncate when the limit is exceeded, use MaxLengthEnforcement.none instead of maxLengthEnforced: false.

Code before migration:

TextField(
  maxLength: 6,
  maxLengthEnforced: false,
)

Code after migration:

TextField(
  maxLength: 6,
  maxLengthEnforcement: MaxLengthEnforcement.none,
)

For CupertinoTextField, which isn't able to show an error message, just don't set the maxLength value.

Code before migration:

CupertinoTextField(
  maxLength: 6,
  maxLengthEnforced: false,
)

Code after migration:

CupertinoTextField()

To enforce the limit, but not for composing text

To avoid truncating text while the user is inputting text by using composition, specify MaxLengthEnforcement.truncateAfterCompositionEnds. This behavior allows input methods that use composing regions larger than the resulting text, as is common for example with Chinese, Japanese, and Korean (CJK) text, to temporarily ignore the limit until editing is complete.

Gboard's English keyboard on Android (and many other Android input methods) creates a composing region for the word being entered. When used in a truncateAfterCompositionEnds text field, the user won't be stopped right away at the maxLength limit. Consider the enforced option if you are confident that the text field will not be used with input methods that use temporarily long composing regions such as CJK text.

Code for the implementation:

TextField(
  maxLength: 6,
  maxLengthEnforcement: MaxLengthEnforcement.truncateAfterCompositionEnds, // Temporarily lifts the limit.
)

Be wary of assuming input will not use composing regions

It is tempting when targeting a particular locale to assume that all users will be satisfied with input from that locale. For example, forum software targeting an English-language community might be assumed to only need to deal with English text. However, this kind of assumption is often incorrect. For example, maybe the English-language forum participants will want to discuss Japanese anime or Vietnamese cooking. Maybe one of the participants is Korean and prefers to express their name in their native ideographs. For this reason, freeform fields should rarely use the enforced value and should instead prefer the truncateAfterCompositionEnds value if at all possible.