feat(ios): honor textDecorationStyle on Text decorations (#56769)

Summary:
`textDecorationStyle` is declared on `TextStyleIOS` in the public types but `wavy` is silently dropped: Fabric's C++ enum doesn't include `Wavy`, and UIKit's `NSUnderlineStyle` has no native wavy pattern bit. Separately, `dotted` and `dashed` map to `NSUnderlineStylePatternDot` / `NSUnderlineStylePatternDash` which don't match browser geometry on iOS.

This PR adds `TextDecorationStyle::Wavy` to the shared Fabric primitives / conversions (also unblocks the same value on Android, see companion PR https://github.com/facebook/react-native/issues/56768) and renders wavy / dotted / dashed decorations with custom Core Graphics paths.

**Implementation:**
- Wavy ranges are tagged with a custom `RCTCustomDecorationAttributeName` (storing the line kinds, stroke color, and style key) in `RCTAttributedTextUtils.mm` and painted by `RCTTextLayoutManager.mm` after `drawGlyphsForGlyphRange:`. Wavy uses an adaptation of WebKit's formula from `Source/WebCore/style/InlineTextBoxStyle.cpp` (`controlPointDistance = thickness * 1.5 + 0.5`, one cubic Bezier per wavelength, control points at the midpoint above and below the y-axis). At iOS point sizes the literal Blink amplitude renders as a very pronounced wave because Core Graphics paints in points (not device pixels), so the constants are dialed back to read as a clear-but-subtle browser-style wave at typical text sizes.
- Dotted uses a custom CG path with a zero-length dash + round line caps, producing actual circular dots at `2 * thickness` spacing.
- Dashed uses a custom CG path with `[2 * thickness, thickness]` intervals — short rectangular dashes with a tight gap, closer to Safari's geometry than UIKit's default.
- Solid and double continue to use UIKit's native `NSUnderlineStyle` pattern bits, so this PR does not touch the long-standing iOS Arial+bold solid-underline rendering bug tracked in https://github.com/facebook/react-native/issues/53935.
- The wavy drawing loop iterates `while x < x2` so the final cycle continues through the last character (including trailing punctuation that would otherwise be visually uncovered when the run width is not an integer multiple of the wavelength).

Companion PRs (independent, also targeting `main`):
- https://github.com/facebook/react-native/issues/56767 — fix(android): textDecorationColor on underlines + strikethroughs. Resolves https://github.com/facebook/react-native/issues/4579 (2015).
- https://github.com/facebook/react-native/issues/56768 — feat(android): textDecorationStyle solid/double/dotted/dashed/wavy. Shares the `TextDecorationStyle::Wavy` enum addition; whichever lands first leaves the other with a trivial conflict to resolve.

## Changelog:

[IOS] [ADDED] - `textDecorationStyle: 'wavy'` for `<Text>` (custom CoreGraphics path)
[IOS] [CHANGED] - `textDecorationStyle: 'dotted'` and `'dashed'` for `<Text>` render with custom CoreGraphics paths instead of UIKit pattern bits, matching browser geometry more closely

Pull Request resolved: https://github.com/facebook/react-native/pull/56769

Test Plan:
See the screenshot comparisons here:

https://www.internalfb.com/compare-screenshots-from-diff/D104680636

{F1990979243}

----

Side-by-side comparison on iPhone 17 sim (iOS 26.4) of a `<Text>` with `textDecorationLine="underline"` and `textDecorationStyle` cycling through `solid` / `double` / `dotted` / `dashed` / `wavy`, verified against Safari rendering of the same CSS. Trailing periods now fall under the wavy stroke. Verified with `textDecorationColor` set distinct from the foreground color.

```tsx
<Text style={{
  color: 'black',
  textDecorationLine: 'underline',
  textDecorationStyle: 'wavy',
  textDecorationColor: '#ff00aa',
}}>
  Hello
</Text>
```

Reviewed By: cipolleschi

Differential Revision: D104680636

Pulled By: cortinico

fbshipit-source-id: ac96e5b36530f7d243a4b85a67c576b62fe99866
This commit is contained in:
Evan Jacobs authored and meta-codesync[bot] committed 2026-06-09 10:18:34 -07:00
1 parent d205267a5f
commit 9d037509bf
5 files changed
+240 -23

No files matched your search

@@ -19,6 +19,17 @@ NSString *const RCTAttributedStringEventEmitterKey = @"EventEmitter";
// String representation of either `role` or `accessibilityRole`
NSString *const RCTTextAttributesAccessibilityRoleAttributeName = @"AccessibilityRole";
// Custom attribute key for ranges whose decoration line cannot be rendered
// faithfully via UIKit's `NSUnderlineStyle` pattern bits (wavy has no native
// equivalent; dotted/dashed don't match the geometry browsers use). These
// ranges are painted by `RCTTextLayoutManager`'s drawing pass.
//
// Stored as an NSDictionary:
// @"lines": NSArray of @"underline" / @"line-through"
// @"color": UIColor stroke color
// @"style": NSString — @"wavy" | @"dotted" | @"dashed"
NSString *const RCTCustomDecorationAttributeName = @"RCTCustomDecoration";
/*
* Creates `NSTextAttributes` from given `facebook::react::TextAttributes`
*/
@@ -240,29 +240,56 @@ NSMutableDictionary<NSAttributedStringKey, id> *RCTNSTextAttributesFromTextAttri
// Decoration
if (textAttributes.textDecorationLineType.value_or(TextDecorationLineType::None) != TextDecorationLineType::None) {
auto textDecorationLineType = textAttributes.textDecorationLineType.value();
NSUnderlineStyle style = RCTNSUnderlineStyleFromTextDecorationStyle(
textAttributes.textDecorationStyle.value_or(TextDecorationStyle::Solid));
auto textDecorationStyleValue = textAttributes.textDecorationStyle.value_or(TextDecorationStyle::Solid);
UIColor *textDecorationColor = RCTUIColorFromSharedColor(textAttributes.textDecorationColor);
// Underline
if (textDecorationLineType == TextDecorationLineType::Underline ||
textDecorationLineType == TextDecorationLineType::UnderlineStrikethrough) {
attributes[NSUnderlineStyleAttributeName] = @(style);
if (textDecorationColor) {
attributes[NSUnderlineColorAttributeName] = textDecorationColor;
// Custom drawing for styles UIKit can't render faithfully: wavy (no
// native value), and dotted/dashed (UIKit's pattern bits don't match
// browser geometry). The other styles continue to use NSUnderlineStyle.
bool needsCustomDrawing = textDecorationStyleValue == TextDecorationStyle::Wavy ||
textDecorationStyleValue == TextDecorationStyle::Dotted ||
textDecorationStyleValue == TextDecorationStyle::Dashed;
if (needsCustomDrawing) {
UIColor *strokeColor = (textDecorationColor != nil) ? textDecorationColor
: RCTUIColorFromSharedColor(textAttributes.foregroundColor);
NSMutableArray<NSString *> *lines = [NSMutableArray array];
if (textDecorationLineType == TextDecorationLineType::Underline ||
textDecorationLineType == TextDecorationLineType::UnderlineStrikethrough) {
[lines addObject:@"underline"];
}
}
if (textDecorationLineType == TextDecorationLineType::Strikethrough ||
textDecorationLineType == TextDecorationLineType::UnderlineStrikethrough) {
[lines addObject:@"line-through"];
}
NSString *styleKey = textDecorationStyleValue == TextDecorationStyle::Wavy
? @"wavy"
: (textDecorationStyleValue == TextDecorationStyle::Dotted ? @"dotted" : @"dashed");
attributes[RCTCustomDecorationAttributeName] = @{
@"lines" : lines,
@"color" : (strokeColor != nil) ? strokeColor : [UIColor labelColor],
@"style" : styleKey
};
} else {
NSUnderlineStyle style = RCTNSUnderlineStyleFromTextDecorationStyle(textDecorationStyleValue);
// Strikethrough
if (textDecorationLineType == TextDecorationLineType::Strikethrough ||
textDecorationLineType == TextDecorationLineType::UnderlineStrikethrough) {
attributes[NSStrikethroughStyleAttributeName] = @(style);
// Underline
if (textDecorationLineType == TextDecorationLineType::Underline ||
textDecorationLineType == TextDecorationLineType::UnderlineStrikethrough) {
attributes[NSUnderlineStyleAttributeName] = @(style);
if (textDecorationColor) {
attributes[NSStrikethroughColorAttributeName] = textDecorationColor;
if (textDecorationColor != nil) {
attributes[NSUnderlineColorAttributeName] = textDecorationColor;
}
}
// Strikethrough
if (textDecorationLineType == TextDecorationLineType::Strikethrough ||
textDecorationLineType == TextDecorationLineType::UnderlineStrikethrough) {
attributes[NSStrikethroughStyleAttributeName] = @(style);
if (textDecorationColor != nil) {
attributes[NSStrikethroughColorAttributeName] = textDecorationColor;
}
}
}
}
@@ -7,6 +7,8 @@
#import "RCTTextLayoutManager.h"
#import <array>
#import "RCTAttributedTextUtils.h"
#import <React/NSTextStorage+FontScaling.h>
@@ -95,6 +97,137 @@ static NSLineBreakMode RCTNSLineBreakModeFromEllipsizeMode(EllipsizeMode ellipsi
CGContextRestoreGState(context);
#endif
// Custom decoration pass: enumerate `RCTCustomDecorationAttributeName`
// ranges and paint each one ourselves. Covers wavy (no UIKit equivalent),
// dotted, and dashed (UIKit's pattern bits don't match browser geometry).
{
CGContextRef ctx = UIGraphicsGetCurrentContext();
if (ctx != nullptr) {
NSRange charRange = [layoutManager characterRangeForGlyphRange:glyphRange actualGlyphRange:nullptr];
[textStorage
enumerateAttribute:RCTCustomDecorationAttributeName
inRange:charRange
options:0
usingBlock:^(NSDictionary *_Nullable attrs, NSRange attrRange, __unused BOOL *stop) {
if (attrs == nil) {
return;
}
NSArray<NSString *> *lines = attrs[@"lines"];
UIColor *strokeColor = attrs[@"color"];
NSString *style = attrs[@"style"];
UIFont *font = [textStorage attribute:NSFontAttributeName
atIndex:attrRange.location
effectiveRange:nullptr];
if (font == nil || strokeColor == nil || style == nil) {
return;
}
CGFloat fontSize = font.pointSize;
// Thickness scales with the type size so the decoration
// remains visible at small sizes and proportionate at
// large ones. ~`fontSize / 12` plus a 1.5pt floor.
CGFloat thickness = MAX(fontSize / 12.0f, 1.5f);
CGFloat wavyWavelength = 1.0f + 2.0f * round(2.0f * thickness + 0.5f);
CGFloat wavyCpDistance = 0.5f + round(3.0f * thickness + 0.5f);
NSRange targetGlyphRange = [layoutManager glyphRangeForCharacterRange:attrRange
actualCharacterRange:nullptr];
CGContextSaveGState(ctx);
CGContextSetStrokeColorWithColor(ctx, strokeColor.CGColor);
CGContextSetLineWidth(ctx, thickness);
CGContextSetShouldAntialias(ctx, YES);
if ([style isEqualToString:@"dotted"]) {
const std::array<CGFloat, 2> dotIntervals = {0.0f, thickness * 2.0f};
CGContextSetLineDash(ctx, 0, dotIntervals.data(), dotIntervals.size());
CGContextSetLineCap(ctx, kCGLineCapRound);
} else if ([style isEqualToString:@"dashed"]) {
const std::array<CGFloat, 2> dashIntervals = {thickness * 2.0f, thickness};
CGContextSetLineDash(ctx, 0, dashIntervals.data(), dashIntervals.size());
CGContextSetLineCap(ctx, kCGLineCapButt);
} else {
CGContextSetLineCap(ctx, kCGLineCapRound);
}
[layoutManager
enumerateLineFragmentsForGlyphRange:targetGlyphRange
usingBlock:^(
CGRect lineRect,
__unused CGRect usedRect,
NSTextContainer *_Nonnull container,
NSRange lineGlyphRange,
__unused BOOL *_Nonnull innerStop) {
NSRange intersection =
NSIntersectionRange(targetGlyphRange, lineGlyphRange);
if (intersection.length == 0) {
return;
}
CGRect firstGlyphRect = [layoutManager
boundingRectForGlyphRange:NSMakeRange(intersection.location, 1)
inTextContainer:container];
CGRect lastGlyphRect = [layoutManager
boundingRectForGlyphRange:NSMakeRange(
NSMaxRange(intersection) - 1, 1)
inTextContainer:container];
CGFloat x1 = firstGlyphRect.origin.x + frame.origin.x;
CGFloat x2 = CGRectGetMaxX(lastGlyphRect) + frame.origin.x;
CGFloat baseline =
lineRect.origin.y + font.ascender + frame.origin.y;
// NOLINTNEXTLINE(cppcoreguidelines-init-variables)
for (NSString *line in lines) {
CGFloat y = 0.0f;
if ([line isEqualToString:@"underline"]) {
if ([style isEqualToString:@"wavy"]) {
y = baseline + 1.0f;
} else {
y = baseline + thickness + 1.0f;
}
} else {
y = baseline - (font.ascender + font.descender) / 2.0f + 1.0f;
}
if ([style isEqualToString:@"wavy"]) {
CGContextSaveGState(ctx);
CGContextClipToRect(
ctx,
CGRectMake(
x1,
y - wavyCpDistance - thickness,
x2 - x1,
2 * wavyCpDistance + 2 * thickness));
CGContextBeginPath(ctx);
CGContextMoveToPoint(ctx, x1, y);
CGFloat step = wavyWavelength / 2.0f;
CGFloat wx = x1;
while (wx < x2) {
CGFloat midX = wx + step;
CGContextAddCurveToPoint(
ctx,
midX,
y + wavyCpDistance,
midX,
y - wavyCpDistance,
wx + wavyWavelength,
y);
wx += wavyWavelength;
}
CGContextStrokePath(ctx);
CGContextRestoreGState(ctx);
} else {
CGContextBeginPath(ctx);
CGContextMoveToPoint(ctx, x1, y);
CGContextAddLineToPoint(ctx, x2, y);
CGContextStrokePath(ctx);
}
}
}];
CGContextRestoreGState(ctx);
}];
}
}
if (block != nil) {
__block UIBezierPath *highlightPath = nil;
NSRange characterRange = [layoutManager characterRangeForGlyphRange:glyphRange actualGlyphRange:NULL];
@@ -106,12 +106,17 @@ inline static NSUnderlineStyle RCTNSUnderlineStyleFromTextDecorationStyle(
return NSUnderlineStyleSingle;
case facebook::react::TextDecorationStyle::Double:
return NSUnderlineStyleDouble;
// Dotted, dashed, and wavy are tagged with
// `RCTCustomDecorationAttributeName` in `RCTAttributedTextUtils.mm` and
// painted by `RCTTextLayoutManager.mm`'s drawing pass; UIKit's pattern
// bits don't match the geometry browsers use, and there is no native
// wavy value at all. These branches are unreachable in normal flow; the
// returned values keep the switch exhaustive.
case facebook::react::TextDecorationStyle::Dashed:
return NSUnderlineStylePatternDash | NSUnderlineStyleSingle;
return NSUnderlineStyleSingle;
case facebook::react::TextDecorationStyle::Dotted:
return NSUnderlineStylePatternDot | NSUnderlineStyleSingle;
return NSUnderlineStyleSingle;
case facebook::react::TextDecorationStyle::Wavy:
// No native NSUnderlineStyle for wavy; fall back to solid.
return NSUnderlineStyleSingle;
}
}
@@ -881,6 +881,14 @@ const examples = [
}}>
Dotted underline with custom color
</Text>
<Text
style={{
textDecorationLine: 'underline',
textDecorationStyle: 'wavy',
textDecorationColor: 'red',
}}>
Wavy underline (red)
</Text>
<Text style={{textDecorationLine: 'none'}}>None textDecoration</Text>
<Text
style={{
@@ -913,8 +921,41 @@ const examples = [
}}>
Dotted line-through with custom color
</Text>
<Text style={{textDecorationLine: 'underline line-through'}}>
Both underline and line-through
<Text
style={{
textDecorationLine: 'line-through',
textDecorationStyle: 'wavy',
textDecorationColor: 'red',
}}>
Wavy line-through (red)
</Text>
<Text
style={{
textDecorationLine: 'underline line-through',
textDecorationStyle: 'wavy',
}}>
Both underline and line-through (wavy)
</Text>
<Text>
Mixed text with{' '}
<Text style={{textDecorationLine: 'underline'}}>underline</Text> and{' '}
<Text style={{textDecorationLine: 'line-through'}}>
line-through
</Text>{' '}
text nodes
</Text>
<Text>
Unstyled text{' '}
<Text
style={{
textDecorationLine: 'line-through',
textDecorationStyle: 'wavy',
textDecorationColor: 'red',
}}>
with wavy strike-through that wraps across multiple lines to
verify continuity
</Text>{' '}
normal text
</Text>
</View>
);