# Soft hyphens render at line breaks

> Text now shows a hyphen when a line breaks at a soft hyphen (U+00AD), and TextStyle.getParagraphStyle has a new hyphens parameter.




:::important
These breaking change docs are accurate, as of the release
under which they are published. Over time, the
workarounds described here might become inaccurate.
We don't, in general, keep these breaking change docs up
to date as of each release.

The [breaking change index file](/release/breaking-changes)
lists the docs created for each release.
:::


## 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 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.

## Migration guide

### Keep the old rendering {: #keep-the-old-rendering }

To keep soft hyphens invisible, pass `Hyphens.hidden`.

Code before migration:

```dart
Text('inter\u00ADnational')
```

Code after migration:

```dart
Text('inter\u00ADnational', 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: 3.49.0-1.0.pre-294<br>
On the web, landed in version: 3.50.0-1.0.pre-109<br>
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][]
* [Render soft hyphens on Skwasm][pr-193850]
* [Render soft hyphens on CanvasKit][pr-194339]

[`Hyphens`]: https://api.flutter.dev/flutter/dart-ui/Hyphens.html
[`ParagraphStyle`]: https://api.flutter.dev/flutter/dart-ui/ParagraphStyle-class.html
[`RichText`]: https://api.flutter.dev/flutter/widgets/RichText-class.html
[`Text`]: https://api.flutter.dev/flutter/widgets/Text-class.html
[`TextPainter`]: https://api.flutter.dev/flutter/painting/TextPainter-class.html
[`TextStyle.getParagraphStyle`]: https://api.flutter.dev/flutter/painting/TextStyle/getParagraphStyle.html
[`TextWidthBasis.longestLine`]: https://api.flutter.dev/flutter/painting/TextWidthBasis.html
[issue-18443]: https://github.com/flutter/flutter/issues/18443
[Support soft hyphen (U+00AD) rendering with a Hyphens API]: https://github.com/flutter/flutter/pull/185152
[pr-193850]: https://github.com/flutter/flutter/pull/193850
[pr-194339]: https://github.com/flutter/flutter/pull/194339