/attributed-string

name: attributed-string
description: AttributedString patterns for rich text formatting, alignment, selection, and SwiftUI integration. Use when working with styled text, text editing, or AttributedString APIs.
allowed-tools: [Read, Glob, Grep]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

AttributedString Patterns

Correct API shapes and patterns for Foundation's `AttributedString`. Covers creating styled text, applying attributes to ranges, text alignment, writing direction, line height control, text selection and editing, discontiguous substrings, and SwiftUI integration.

When This Skill Activates

Use this skill when the user:

• Asks about **AttributedString** creation or manipulation
• Wants to **style text** with fonts, colors, underlines, or other attributes
• Mentions **text alignment**, **writing direction**, or **line height**
• Asks about **text selection** or **text editing** with AttributedString
• Wants to work with **DiscontiguousAttributedSubstring** or **RangeSet**
• Mentions **TextEditor** with **AttributedString** in SwiftUI
• Asks about **rich text** formatting in Swift
• Wants to **replace** or **modify** text within an AttributedString
• Mentions **paragraphStyle**, **textSelectionAffinity**, or **AttributedTextSelection**

Decision Tree

What do you need with AttributedString?
|
+-- Create or style text
|   |
|   +-- Simple inline attributes (font, color)
|   |   --> Creating and Styling section
|   |
|   +-- Paragraph-level formatting (alignment, line height)
|       --> Text Alignment and Formatting section
|
+-- Control text layout
|   |
|   +-- Writing direction (LTR / RTL)
|   |   --> Writing Direction and Line Height section
|   |
|   +-- Line spacing / height
|       --> Writing Direction and Line Height section
|
+-- Edit or select text programmatically
|   |
|   +-- Replace selection with characters or AttributedString
|   |   --> Text Selection and Editing section
|   |
|   +-- Work with multiple non-contiguous ranges
|       --> DiscontiguousAttributedSubstring section
|
+-- Display in SwiftUI
    --> SwiftUI Integration section

API Availability

| API | Minimum Version | Notes | |-----|----------------|-------| | `AttributedString` | iOS 15 / macOS 12 | Swift-native replacement for NSAttributedString | | `AttributedString.paragraphStyle` | iOS 15 / macOS 12 | Uses NSMutableParagraphStyle | | `AttributedString.writingDirection` | iOS 26 / macOS 26 | New in 2025 | | `AttributedString.LineHeight` | iOS 26 / macOS 26 | `.exact(points:)`, `.multiple(factor:)`, `.loose` | | `AttributedString.alignment` | iOS 26 / macOS 26 | `.left`, `.center`, `.right` | | `AttributedTextSelection` | iOS 26 / macOS 26 | Programmatic text selection | | `replaceSelection(_:withCharacters:)` | iOS 26 / macOS 26 | Replace selection with plain characters | | `replaceSelection(_:with:)` | iOS 26 / macOS 26 | Replace selection with AttributedString | | `DiscontiguousAttributedSubstring` | iOS 26 / macOS 26 | Non-contiguous range selections | | `AttributedString.utf8` | iOS 26 / macOS 26 | UTF-8 code unit view | | `TextEditor(text:selection:)` with AttributedString | iOS 26 / macOS 26 | SwiftUI rich text editing | | `.textSelectionAffinity(_:)` | iOS 26 / macOS 26 | Control cursor affinity at line boundaries |

Top 5 Mistakes

| # | Mistake | Fix | |---|---------|-----| | 1 | Using `NSAttributedString` in new Swift code | Use `AttributedString` (iOS 15+) for type-safe, Swift-native attributes | | 2 | Applying range-based attributes without checking the range exists | Always safely unwrap the result of `text.range(of:)` before subscripting | | 3 | Forgetting that `AttributedString` is a value type | Mutations require `var`, not `let`; assign attributes after declaring as `var` | | 4 | Building `NSMutableParagraphStyle` when new alignment API is available | Use `text.alignment = .center` on iOS 26+ instead of manual paragraph styles | | 5 | Modifying the original string instead of the selection when using `replaceSelection` | Pass the selection as `inout` and let the API update the selection range for you |

Creating and Styling

Basic Initialization

// Plain text
let plain = AttributedString("Hello, world!")

// With attributes applied inline
var bold = AttributedString("Bold text")
bold.font = .boldSystemFont(ofSize: 16)

Applying Attributes to Ranges

var text = AttributedString("Styled text")
text.foregroundColor = .red
text.backgroundColor = .yellow
text.font = .systemFont(ofSize: 14)

// Attribute on a specific range
if let range = text.range(of: "Styled") {
    text[range].underlineStyle = .single
    text[range].underlineColor = .blue
}

Creating from a Substring

let source = AttributedString("Hello, world!")
if let range = source.range(of: "world") {
    let substring = source[range]
    let extracted = AttributedString(substring) // standalone copy
}

| Pattern | Verdict | |---------|---------| | `var text = AttributedString("...")` then mutate | Correct | | `let text = AttributedString("...")` then mutate | Will not compile -- value type requires `var` | | Force-unwrapping `text.range(of:)!` | Fragile -- use `if let` or `guard let` |

Text Alignment and Formatting

Legacy Approach (iOS 15+)

var paragraph = AttributedString("Centered paragraph of text")
let style = NSMutableParagraphStyle()
style.alignment = .center
paragraph.paragraphStyle = style

Modern Approach (iOS 26+)

var paragraph = AttributedString("Centered paragraph of text")
paragraph.alignment = .center

Available `TextAlignment` values:

| Value | Description | |-------|-------------| | `.left` | Left-aligned text | | `.right` | Right-aligned text | | `.center` | Center-aligned text |

Writing Direction and Line Height

Writing Direction (iOS 26+)

var text = AttributedString("Hello عربي")
text.writingDirection = .rightToLeft

| Value