From fe73a7e0d96cb1e087a26a9e2570eb53c29a06df Mon Sep 17 00:00:00 2001 From: David Bebawy Date: Wed, 30 Sep 2026 13:42:19 -0400 Subject: [PATCH 1/4] Add breaking change page for soft hyphen rendering Covers flutter/flutter#185152: soft hyphens (U+00AD) now render at line breaks, and TextStyle.getParagraphStyle gained a hyphens parameter. --- .../content/release/breaking-changes/index.md | 2 + .../breaking-changes/soft-hyphen-rendering.md | 132 ++++++++++++++++++ 2 files changed, 134 insertions(+) create mode 100644 sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md diff --git a/sites/docs/src/content/release/breaking-changes/index.md b/sites/docs/src/content/release/breaking-changes/index.md index 97230259b7..ac5d6d33ee 100644 --- a/sites/docs/src/content/release/breaking-changes/index.md +++ b/sites/docs/src/content/release/breaking-changes/index.md @@ -40,11 +40,13 @@ They're sorted by release and listed in alphabetical order: * [Migrate to standalone `material_ui` and `cupertino_ui` packages][] * [Restrict Android engine flags in release mode][] * [Removal of `useInheritedMediaQuery`][] +* [Soft hyphens render at line breaks][] [Added enabled property and made onChanged optional for DropdownButton]: /release/breaking-changes/dropdownbutton-enabled-property [Migrate to standalone `material_ui` and `cupertino_ui` packages]: /release/breaking-changes/material-ui-and-cupertino-ui [Restrict Android engine flags in release mode]: /release/breaking-changes/restrict-android-engine-flags-release-mode [Removal of `useInheritedMediaQuery`]: /release/breaking-changes/remove-useInheritedMediaQuery +[Soft hyphens render at line breaks]: /release/breaking-changes/soft-hyphen-rendering ### Released in Flutter 3.47 diff --git a/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md b/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md new file mode 100644 index 0000000000..f8d8e03364 --- /dev/null +++ b/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md @@ -0,0 +1,132 @@ +--- +title: Soft hyphens render at line breaks +description: >- + Text now shows a hyphen when a line breaks at a soft hyphen (U+00AD), + and TextStyle.getParagraphStyle has a new hyphens parameter. +--- + +{% render "docs/breaking-changes.md" %} + +## Summary + +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. + +## Background + +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 that contains a soft hyphen now shows a hyphen +wherever a line breaks at it. +The hyphen counts toward the line's width, +so it can change `Paragraph.longestLine`, the size of text laid out with +[`TextWidthBasis.longestLine`][], and hit testing for that text. +Golden image tests that contain such text might need updating. + +**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. + +## Migration guide + +### Keep the old rendering {: #keep-the-old-rendering } + +To keep soft hyphens invisible, pass `Hyphens.hidden`. + +Code before migration: + +```dart +Text('inter­national') +``` + +Code after migration: + +```dart +Text('inter­national', hyphens: Hyphens.hidden) +``` + +### Update overrides of `getParagraphStyle` {: #update-overrides } + +If you override `TextStyle.getParagraphStyle`, add the new parameter. + +Code before migration: + +```dart +@override +ui.ParagraphStyle getParagraphStyle({ + TextAlign? textAlign, + // ...other parameters... + StrutStyle? strutStyle, +}) { + // ... +} +``` + +Code after migration: + +```dart +@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. + +## Timeline + +Landed in version: Not yet
+In stable release: Not yet + +## References + +API documentation: + +* [`Hyphens`][] +* [`ParagraphStyle`][] +* [`RichText`][] +* [`Text`][] +* [`TextPainter`][] +* [`TextStyle.getParagraphStyle`][] + +Relevant issues: + +* [Support soft hyphenation][issue-18443] + +Relevant PRs: + +* [Support soft hyphen (U+00AD) rendering with a Hyphens API][] + +[`Hyphens`]: {{site.api}}/flutter/dart-ui/Hyphens.html +[`ParagraphStyle`]: {{site.api}}/flutter/dart-ui/ParagraphStyle-class.html +[`RichText`]: {{site.api}}/flutter/widgets/RichText-class.html +[`Text`]: {{site.api}}/flutter/widgets/Text-class.html +[`TextPainter`]: {{site.api}}/flutter/painting/TextPainter-class.html +[`TextStyle.getParagraphStyle`]: {{site.api}}/flutter/painting/TextStyle/getParagraphStyle.html +[`TextWidthBasis.longestLine`]: {{site.api}}/flutter/painting/TextWidthBasis.html +[issue-18443]: {{site.repo.flutter}}/issues/18443 +[Support soft hyphen (U+00AD) rendering with a Hyphens API]: {{site.repo.flutter}}/pull/185152 From 66bb0b3cf78d87d6ad284559d402eddefd215777 Mon Sep 17 00:00:00 2001 From: David Bebawy Date: Wed, 30 Sep 2026 16:26:33 -0400 Subject: [PATCH 2/4] Clarify soft hyphen page: no hit-testing change, web and editable text Lines still break in the same places, and hit testing isn't affected. Note that the web doesn't render soft hyphens yet, and that editable text and SelectableText can't opt out yet. Use \u00AD escapes in the code samples so the soft hyphen is visible. --- .../breaking-changes/soft-hyphen-rendering.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md b/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md index f8d8e03364..436e9912b1 100644 --- a/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md +++ b/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md @@ -32,11 +32,18 @@ This change affects apps in two ways. **Rendering.** Text that contains a soft hyphen now shows a hyphen wherever a line breaks at it. -The hyphen counts toward the line's width, -so it can change `Paragraph.longestLine`, the size of text laid out with -[`TextWidthBasis.longestLine`][], and hit testing for that text. +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 aren't rendered yet. +Editable text, 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. + **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` @@ -53,13 +60,13 @@ To keep soft hyphens invisible, pass `Hyphens.hidden`. Code before migration: ```dart -Text('inter­national') +Text('inter\u00ADnational') ``` Code after migration: ```dart -Text('inter­national', hyphens: Hyphens.hidden) +Text('inter\u00ADnational', hyphens: Hyphens.hidden) ``` ### Update overrides of `getParagraphStyle` {: #update-overrides } From 9ad6772b6baada037956479da63735ccce4743b5 Mon Sep 17 00:00:00 2001 From: David Bebawy Date: Mon, 5 Oct 2026 14:50:22 -0400 Subject: [PATCH 3/4] Address review: rendering wording and landed-in version Say the hyphen shows wherever a line breaks at a soft hyphen, and fill in the version where the change landed on master. --- .../release/breaking-changes/soft-hyphen-rendering.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md b/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md index 436e9912b1..65c83b7bcb 100644 --- a/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md +++ b/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md @@ -30,8 +30,8 @@ and `dart:ui`'s [`ParagraphStyle`][] takes a `Hyphens` value: This change affects apps in two ways. -**Rendering.** Text that contains a soft hyphen now shows a hyphen -wherever a line breaks at it. +**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 @@ -106,7 +106,7 @@ Otherwise, accepting and ignoring the parameter is enough. ## Timeline -Landed in version: Not yet
+Landed in version: 3.49.0-1.0.pre-294
In stable release: Not yet ## References From 8efe6b43c81e76e0a094f3c78522c8566893fcb6 Mon Sep 17 00:00:00 2001 From: David Bebawy Date: Mon, 5 Oct 2026 15:08:47 -0400 Subject: [PATCH 4/4] Clarify which widgets can't opt out of soft hyphen rendering SelectableText isn't editable, but it's built on EditableText, as TextField is. --- .../content/release/breaking-changes/soft-hyphen-rendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md b/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md index 65c83b7bcb..c04e1b64b8 100644 --- a/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md +++ b/sites/docs/src/content/release/breaking-changes/soft-hyphen-rendering.md @@ -40,7 +40,7 @@ Golden image tests that contain such text might need updating. This applies to all platforms except the web, where soft hyphens aren't rendered yet. -Editable text, such as `TextField`, and `SelectableText` +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.