sitapix/txt-attribute-keys

Attribute Keys Reference

Authored against iOS 26.x / Swift 6.x / Xcode 26.x.

This skill catalogs NSAttributedString.Key values, their value types, and which keys actually render in each text view. The catalog and view-compatibility matrix shift with each Foundation release — Apple has added keys (.adaptiveImageGlyph, .textAlternatives) and changed which SwiftUI text APIs honor which keys without warning. Before quoting any specific key, value type, or compatibility cell as current, fetch the official entry via Sosumi (sosumi.ai/documentation/foundation/nsattributedstring/key). The tables here are a starting point, not a contract.

The compatibility matrix in particular is empirical, not declared. SwiftUI Text silently drops attributes it does not understand; UITextView in TextKit 1 mode renders attributes TextKit 2 mode does not; AppKit text views support keys (superscript, toolTip, textBlock) that have no UIKit equivalent at all. If an attribute "does nothing," verify against a runtime test before assuming a bug — the more common cause is a key that the destination view ignores by design.

Contents

• Typography keys
• Color keys
• Decoration keys
• Layout and structure keys
• Content keys
• AppKit-only keys
• Underline and strikethrough styles
• Paragraph style and lists
• View compatibility
• RTF round-trip
• Common Mistakes
• References

Typography keys

These control glyph selection, sizing, spacing, and synthetic transforms. Value types are bridged to their Objective-C equivalents — Swift CGFloat is wrapped in NSNumber when stored in the dictionary.

| Key | Value type | Effect | |-----|-----------|--------| | .font | UIFont / NSFont | Typeface, size, weight | | .kern | NSNumber (CGFloat) | Inter-character spacing in points (absolute) | | .tracking | NSNumber (CGFloat) | Tracking that scales with font size (iOS 14+, macOS 11+) | | .ligature | NSNumber (Int) | 0 = none, 1 = default, 2 = all (AppKit) | | .baselineOffset | NSNumber (CGFloat) | Vertical shift from baseline | | .obliqueness | NSNumber (CGFloat) | Synthetic italic, positive leans right | | .expansion | NSNumber (CGFloat) | Horizontal stretch, 0 = normal | | .verticalGlyphForm | NSNumber (Int) | 0 = horizontal, 1 = vertical (CJK) |

.kern and .tracking look interchangeable but differ at scale. .kern is in points and stays constant — 2pt of kern reads thin at 12pt and barely visible at 48pt. .tracking scales with the font and is the right choice when an attribute should look proportional across sizes.

Color keys

| Key | Value type | Effect | |-----|-----------|--------| | .foregroundColor | UIColor / NSColor | Text color | | .backgroundColor | UIColor / NSColor | Background fill behind glyphs | | .strokeColor | UIColor / NSColor | Outline color | | .strokeWidth | NSNumber (CGFloat) | Outline width — sign matters (see below) | | .shadow | NSShadow | Drop shadow |

.strokeWidth has a sign convention that catches everyone. A positive value renders stroke only — outlined hollow glyphs. A negative value renders fill plus stroke — solid glyphs with an outline on top. Setting .strokeColor: .blue and .strokeWidth: 3.0 produces hollow blue letters; setting .strokeWidth: -3.0 keeps the foreground fill and adds a blue border.

The default .foregroundColor is black, not the semantic label color. Attributed strings created without an explicit foreground render as invisible black text in dark mode. The fix is always-explicit: .foregroundColor: UIColor.label.

Decoration keys

| Key | Value type | Effect | |-----|-----------|--------| | .underlineStyle | NSNumber (NSUnderlineStyle raw value) | Underline pattern | | .underlineColor | UIColor / NSColor | Underline color (nil inherits foreground) | | .strikethroughStyle | NSNumber (NSUnderlineStyle raw value) | Strikethrough pattern | | .strikethroughColor | UIColor / NSColor | Strikethrough color |

Underline and strikethrough share the NSUnderlineStyle option set, combined with bitwise OR. See Underline and strikethrough styles below.

Layout and structure keys

| Key | Value type | Effect | |-----|-----------|--------| | .paragraphStyle | NSParagraphStyle | Per-paragraph layout (see section below) | | .writingDirection | [NSNumber] | Bidi embedding/override levels | | .textEffect | NSAttributedString.TextEffectStyle | Letterpress is the only public value |

A paragraph style applied to a sub-range gets extended to the full paragraph at draw time by fixAttributes — there is no such thing as half-a-paragraph indentation. If a sub-range needs different alignment or indentation, split the paragraph (insert a \n).

Content keys

| Key | Value type | Effect | |-----|-----------|--------| | .attachment | NSTextAttachment | Inline image, view provider, or adaptive glyph carrier | | .link | URL or String | Hyperlink | | .textAlternatives | NSTextAlternatives | Alternative interpretations (autocorrect candidates) | | .adaptiveImageGlyph | NSAdaptiveImageGlyph | Genmoji and stickers, iOS 18+ |

.link accepts either a URL or a String. UITextView and NSTextView render both; SwiftUI Text only renders URL. If a link "doesn't tap" in SwiftUI, the value is probably a String.

AppKit-only keys

These are AppKit-specific and have no UIKit counterpart. Using them in cross-platform code requires #if os(macOS) guards.

| Key | Value type | Effect | |-----|-----------|--------| | .superscript | NSNumber (Int) | Positive = superscript, negative = subscript | | .cursor | NSCursor | Hover cursor | | .toolTip | String | Hover tooltip | | .markedClauseSegment | NSNumber (Int) | CJK marked-text clause index | | .spellingState | NSNumber (Int) | Spelling/grammar squiggle indicator | | .glyphInfo | NSGlyphInfo | Glyph substitution | | .textBlock | NSTextBlock | Table cell — note: forces TextKit 1 |

.textBlock is part of the AppKit-only NSTextTable system and forces a TextKit 2 view to fall back to TextKit 1 the moment it appears. If preserving TextKit 2 features (Writing Tools, viewport rendering) matters, do not use NSTextTable.

Underline and strikethrough styles

NSUnderlineStyle is an option set. Combine line style, pattern, and modifier with .union(_:) or array literal syntax, then store as rawValue:

// Thick dashed underline, words only
let style: NSUnderlineStyle = [.thick, .patternDash, .byWord]

let attrs: [NSAttributedString.Key: Any] = [
    .underlineStyle: style.rawValue,
    .underlineColor: UIColor.systemRed,
]

Line style: .single, .thick, .double. Pattern (combined with style): .patternDot, .patternDash, .patternDashDot, .patternDashDotDot. Modifier: .byWord skips spaces. The same option set is used for .strikethroughStyle.

Paragraph style and lists

NSParagraphStyle is immutable — to change anything, instantiate NSMutableParagraphStyle, configure it, then set it as the value:

let style = NSMutableParagraphStyle()
style.alignment = .natural          // .left / .right / .center / .justified / .natural
style.lineSpacing = 4               // additional space between lines
style.paragraphSpacing = 12         // space after this paragraph
style.paragraphSpacingBefore = 8    // space before this paragraph
style.firstLineHeadIndent = 20
style.headIndent = 10               // subsequent-line indent
style.tailIndent = -10              // negative = inset from right edge
style.lineBreakMode = .byWordWrapping
style.lineBreakStrategy = .standard
style.hyphenationFactor = 0.5       // 0.0 (off) to 1.0 (max)
style.tabStops = [NSTextTab(textAlignment: .left, location: 100)]

NSTextList markers (UIKit iOS 17+, AppKit always): .disc, .circle, .square, .decimal, .lowercaseAlpha, .uppercaseAlpha, .lowercaseRoman, .uppercaseRoman. AppKit adds Latin, hexadecimal, octal, hyphen, and check formats.

style.textLists = [NSTextList(markerFormat: .disc, options: 0)]

View compatibility

This matrix is empirical — verify with a runtime test before assuming a key works. SwiftUI Text in particular drops most attributes silently.

| Attribute | SwiftUI Text | TextEditor (iOS 26+) | UITextView | UILabel | NSTextView | |-----------|:-:|:-:|:-:|:-:|:-:| | .font | yes | yes | yes | yes | yes | | .foregroundColor | yes | yes | yes | yes | yes | | .backgroundColor | yes | yes | yes | yes | yes | | .kern / .tracking | yes | yes | yes | yes | yes | | .underlineStyle | yes | yes | yes | yes | yes | | .strikethroughStyle | yes | yes | yes | yes | yes | | .baselineOffset | yes | yes | yes | yes | yes | | .link | yes (URL only) | yes | yes | no | yes | | .paragraphStyle | no | partial (alignment, line height) | yes | yes | yes | | .shadow | no (use .shadow() modifier) | no | yes | yes | yes | | .strokeColor / .strokeWidth | no | no | yes | yes | yes | | .obliqueness | no | no | yes | yes | yes | | .expansion | no | no | yes | yes | yes | | .textEffect | no | no | yes | yes | yes | | .attachment | no | no | yes | display only | yes | | .adaptiveImageGlyph | no | yes | yes | yes | yes | | .superscript | no | no | no | no | yes (AppKit) | | .toolTip | no | no | no | no | yes (AppKit) | | .textBlock (TextKit 1 only) | no | no | no | no | yes (AppKit) | | .textList | no | no | yes (iOS 17+) | yes | yes |

UITextView with allowsEditingTextAttributes = true shows a B/I/U menu — the only built-in formatting UI. Anything else (size, color, alignment) requires custom UI.

RTF round-trip

Attributes that survive NSAttributedString.DocumentType.rtf archiving:

• .font, .foregroundColor, .backgroundColor, .paragraphStyle
• .underlineStyle, .underlineColor, .strikethroughStyle, .strikethroughColor
• .kern, .baselineOffset
• .link, .attachment, .shadow, .strokeColor, .strokeWidth
• .superscript (AppKit), .textList, .textBlock

Attributes that are lost in RTF:

• .obliqueness, .expansion — may survive if the font supports them as descriptors
• .textEffect (letterpress)
• .adaptiveImageGlyph — Genmoji has its own RTFD-style handling; plain RTF drops it
• Custom attributes — unless you handle RTF custom tags via NSAttributedString.DocumentReadingOptionKey.documentType

For format-preserving storage, RTFD archives or AttributedString Codable encoding preserves more.

Common Mistakes

1. Using String for .link in SwiftUI Text. SwiftUI only renders URL values; a String link is silently ignored. The fix is always .link: URL(string: "...")!.

2. Setting .paragraphStyle on a sub-range and expecting only that range to indent. TextKit's fixAttributes extends paragraph styles to the full paragraph at draw time. Half-a-paragraph indentation does not exist; split the paragraph with \n if you need different formatting.

   // WRONG — second half won't indent because first half wins
   let mutable = NSMutableAttributedString(string: "Header\nBody")
   mutable.addAttribute(.paragraphStyle, value: indented, range: NSRange(location: 7, length: 4))
   
   // CORRECT — paragraph break separates the styles
   let mutable = NSMutableAttributedString(string: "Header\nBody")
   mutable.addAttribute(.paragraphStyle, value: header, range: NSRange(location: 0, length: 6))
   mutable.addAttribute(.paragraphStyle, value: indented, range: NSRange(location: 7, length: 4))
   

3. Mutating NSParagraphStyle directly. NSParagraphStyle is immutable — there are no setters. The error is silent: code compiles, runtime does nothing. Always start from NSMutableParagraphStyle, configure, then set as the attribute value.

4. Hardcoded .foregroundColor: UIColor.black instead of .label. The default attributed-string foreground is opaque black, which becomes invisible in dark mode. Always set .foregroundColor: UIColor.label (or another semantic color) for adaptive behavior.

5. NSTextTable in code that needs Writing Tools. .textBlock forces TextKit 1 fallback the moment it appears in storage. The TextKit 2-only features (inline Writing Tools rewrites, viewport rendering) stop working for the entire view, not just the table. If a layout calls for tables, decide between TextKit 2 features and table rendering before adding the attribute.

6. .kern for "tighter spacing across all sizes." Kern is absolute points; it makes 12pt text look thin and 48pt text look unchanged. For proportional spacing across sizes, use .tracking.

7. AppKit-only keys in cross-platform code. .superscript, .toolTip, .cursor, .textBlock, .textTable exist only on AppKit. Apply them inside #if os(macOS) or extract from the iOS code path entirely.

8. Assuming typingAttributes survives an attributedText set or a selection change. Assigning attributedText on UITextView resets typingAttributes to whatever the new attributed string's last run carries. Selection-change events also clear them. An editor that customizes typing fonts — for example, a Markdown editor that toggles italic for the next-typed run — loses its typing styles every time the user moves the cursor or any code reassigns attributedText. The fix is to keep a sidecar currentTypingAttributes dictionary on the controller and re-apply it inside DispatchQueue.main.async from textViewDidChangeSelection(_:); the async hop is necessary because UIKit clears typing attributes after the delegate returns synchronously.

   var currentTypingAttributes: [NSAttributedString.Key: Any] = [.font: UIFont.preferredFont(forTextStyle: .body)]
   
   func textViewDidChangeSelection(_ textView: UITextView) {
       DispatchQueue.main.async {
           textView.typingAttributes = self.currentTypingAttributes
       }
   }
   

   Related: attributedText getter has copy semantics. Reading textView.attributedText inside textViewDidChange(_:) copies the entire attributed string on every keystroke — at 50KB the per-keystroke cost becomes visible in Time Profiler. For read-only access in hot paths, use textView.textStorage directly; it is the live NSTextStorage and does not copy. The .attributedText getter is only worth it when the caller actually needs an isolated snapshot.

References

• txt-attributed-string — picking AttributedString vs NSAttributedString and converting between them
• txt-attachments — .attachment and .adaptiveImageGlyph lifecycle, view providers, baseline alignment
• txt-colors — semantic colors, dark-mode adaptation, wide-color rendering
• txt-line-breaking — NSParagraphStyle line break, hyphenation, tab stops
• references/latest-apis.md — per-key value type, availability, and Sosumi URL liveness; refreshed against current Apple docs
• NSAttributedString.Key
• NSParagraphStyle
• NSTextList
• NSUnderlineStyle
• NSTextTable (AppKit)