Soft hyphens render at line breaks

When a line of text breaks at a soft hyphen (U+00AD), Flutter now draws a visible hyphen at the end of the line. A new Hyphens enum controls this, and TextStyle.getParagraphStyle has a new hyphens parameter. Classes that override getParagraphStyle must add the parameter.

A soft hyphen marks a place where a word can be broken across lines. Flutter already broke lines at soft hyphens, but never drew the hyphen, so broken words looked cut off.

The new hyphens parameter on Text, RichText, TextPainter, and dart:ui's ParagraphStyle takes a Hyphens value:

• Hyphens.manual (the default) draws a hyphen at the break.
• Hyphens.hidden doesn't draw a hyphen. The soft hyphen is still a place where the line can break.

This change affects apps in two ways.

Rendering. Text now shows a hyphen wherever a line breaks at a soft hyphen. Lines still break in the same places, but the hyphen makes its line wider, so it can change Paragraph.longestLine and the size of text laid out with TextWidthBasis.longestLine. Golden image tests that contain such text might need updating.

This applies to all platforms except the web, where soft hyphens are rendered starting in a later release. Widgets built on EditableText, such as TextField and SelectableText, also render the hyphen but don't have a hyphens parameter yet, so there's no way to opt out for them.

In Flutter 3.50, the hyphen has a few known issues, which a later release fixes:

• It can appear where a line doesn't break at the soft hyphen, such as at the end of the text or before a space or line break.
• It can extend slightly past the width of the paragraph. With the fix, the line breaks earlier instead when the hyphen doesn't fit.
• It isn't highlighted when the text is selected.

To avoid these issues in 3.50, set hyphens: Hyphens.hidden on Text, RichText, or TextPainter.

API. TextStyle.getParagraphStyle gained an optional hyphens parameter. Because Dart requires an override to accept every parameter of the method it overrides, a class that overrides getParagraphStyle no longer compiles until it adds the parameter. This mostly affects test doubles and proxies of TextStyle, not typical app code.

To keep soft hyphens invisible, pass Hyphens.hidden.

Code before migration:

Text('inter\u00ADnational')

Code after migration:

Text('inter\u00ADnational', hyphens: Hyphens.hidden)

If you override TextStyle.getParagraphStyle, add the new parameter.

Code before migration:

@override
ui.ParagraphStyle getParagraphStyle({
  TextAlign? textAlign,
  // ...other parameters...
  StrutStyle? strutStyle,
}) {
  // ...
}

Code after migration:

@override
ui.ParagraphStyle getParagraphStyle({
  TextAlign? textAlign,
  // ...other parameters...
  StrutStyle? strutStyle,
  Hyphens? hyphens,
}) {
  // ...
}

If your override forwards to another getParagraphStyle or constructs a ParagraphStyle, pass hyphens through. Otherwise, accepting and ignoring the parameter is enough.

Landed in version: 3.49.0-1.0.pre-294
On the web, landed in version: 3.50.0-1.0.pre-109
In stable release: Not yet

API documentation:

• Hyphens
• ParagraphStyle
• RichText
• Text
• TextPainter
• TextStyle.getParagraphStyle

Relevant issues:

• Support soft hyphenation

Relevant PRs:

• Support soft hyphen (U+00AD) rendering with a Hyphens API
• Render soft hyphens on Skwasm
• Render soft hyphens on CanvasKit