Apple Text Views

Decision Skills

Use when choosing between SwiftUI Text/TextField/TextEditor, UITextView, or NSTextView — capabilities and tradeoffs.

Family: View And Stack Decisions

Use this skill when the main question is “which text view should I use?” or when behavior depends on the capabilities of a specific view class.

When to Use

• You are choosing among SwiftUI, UIKit, and AppKit text views.
• The question is mostly about capability tradeoffs, not low-level TextKit APIs.
• You need to know whether the problem belongs in Text, TextField, TextEditor, UITextView, or NSTextView.

Quick Decision

Read-only text in SwiftUI -> Text

Single-line input in SwiftUI -> TextField

Multi-line plain-text editing in SwiftUI -> TextEditor

Rich text, TextKit access, syntax highlighting, attachments, or custom layout on iOS -> UITextView

Rich text, field editor behavior, text tables, rulers, printing, or advanced desktop editing on macOS -> NSTextView

Static UIKit label -> UILabel

Simple UIKit/AppKit form input -> UITextField / NSTextField

Core Guidance

Decision Guide

1. Are you editing text?

No -> Prefer Text or UILabel.

Yes -> Go to step 2.

2. Is plain-text SwiftUI editing enough?

Use TextField or TextEditor when all of these are true:

• You only need plain String editing
• You do not need TextKit APIs
• You do not need inline attachments or rich attributed editing
• You can accept SwiftUI’s editing limitations

If any of those are false, move to UITextView or NSTextView.

3. Do you need TextKit or attributed text control?

Use UITextView / NSTextView when you need:

• NSAttributedString or advanced AttributedString bridging
• Layout inspection or fragment-level queries
• Syntax highlighting or custom rendering
• Inline attachments or custom attachment views
• Rich editing commands, menus, or selection behavior
• Writing Tools coordination beyond basic defaults

4. Do you need TextKit 2 specifically?

Use TextKit 1 (NSLayoutManager) when you need:

• Glyph-level access (custom glyph drawing, glyph metrics, shouldGenerateGlyphs)
• Multi-page or multi-column layout (multiple text containers)
• Syntax highlighting via temporary attributes (proven, reliable)
• Text tables (NSTextTable, macOS)
• Printing with full pagination control

Use TextKit 2 (NSTextLayoutManager) when you need:

• Viewport-based layout for large documents
• Writing Tools full inline experience
• Correct complex-script rendering by default (Arabic, Devanagari, CJK)
• Modern rendering and layout APIs

Neither is “legacy” or “modern” — they solve different problems. TextKit 1 is the right choice for glyph-level work even in a brand-new app.

For the actual TextKit 1 vs 2 choice, launch the platform-reference agent.

Common Decisions

Chat composer that grows vertically -> TextField(axis: .vertical) first, UITextView if you need richer editing behavior.

Notes editor with rich text -> UITextView on iOS, NSTextView on macOS.

Syntax-highlighted code editor -> UITextView / NSTextView. TextKit 1 if you need temporary attributes (proven) or glyph metrics; TextKit 2 if you need viewport performance on very large files.

Simple settings field -> TextField, UITextField, or NSTextField.

Markdown display only -> Text if the supported inline subset is enough; otherwise use TextKit-backed rendering.

Need AppKit-only document editor features -> NSTextView.

Related Skills and Agents

• For the full catalog, capabilities tables, and platform-by-platform reference, see reference.md.
• For usage-oriented examples, see examples.md.
• For wrapping UITextView or NSTextView in SwiftUI, launch the platform-reference agent.
• For the TextKit 1 vs 2 decision specifically, use /skill apple-text-layout-manager-selection.
• For TextKit 1 vs 2 architecture, launch the textkit-reference agent.
• For a migration or performance decision, launch the platform-reference agent.
• For debugging weird editor behavior, use /skill apple-text-textkit-diag.

Documentation Scope

This page documents the apple-text-views decision skill. Use it when the main task is choosing the right Apple text API, view, or architecture.

Related

• apple-text: Use when the user has an Apple text-system problem but the right specialist skill is not obvious, or when the request mixes multiple text subsystems.
• apple-text-representable: Use when wrapping UITextView or NSTextView in SwiftUI — binding, focus, sizing, cursor preservation, or update loops.
• apple-text-layout-manager-selection: Use when choosing between TextKit 1 and TextKit 2, evaluating migration risk, or comparing NSLayoutManager vs NSTextLayoutManager.

Sidecar Files

• skills/apple-text-views/examples.md
• skills/apple-text-views/reference.md

Full SKILL.md source

SKILL.md

---
name: apple-text-views
description: Use when choosing between SwiftUI Text/TextField/TextEditor, UITextView, or NSTextView — capabilities and tradeoffs
license: MIT
---

# Apple Text Views

Use this skill when the main question is "which text view should I use?" or when behavior depends on the capabilities of a specific view class.

## When to Use

- You are choosing among SwiftUI, UIKit, and AppKit text views.
- The question is mostly about capability tradeoffs, not low-level TextKit APIs.
- You need to know whether the problem belongs in `Text`, `TextField`, `TextEditor`, `UITextView`, or `NSTextView`.

## Quick Decision

**Read-only text in SwiftUI** -> `Text`

**Single-line input in SwiftUI** -> `TextField`

**Multi-line plain-text editing in SwiftUI** -> `TextEditor`

**Rich text, TextKit access, syntax highlighting, attachments, or custom layout on iOS** -> `UITextView`

**Rich text, field editor behavior, text tables, rulers, printing, or advanced desktop editing on macOS** -> `NSTextView`

**Static UIKit label** -> `UILabel`

**Simple UIKit/AppKit form input** -> `UITextField` / `NSTextField`

## Core Guidance

## Decision Guide

### 1. Are you editing text?

**No** -> Prefer `Text` or `UILabel`.

**Yes** -> Go to step 2.

### 2. Is plain-text SwiftUI editing enough?

Use `TextField` or `TextEditor` when all of these are true:

- You only need plain `String` editing
- You do not need TextKit APIs
- You do not need inline attachments or rich attributed editing
- You can accept SwiftUI's editing limitations

If any of those are false, move to `UITextView` or `NSTextView`.

### 3. Do you need TextKit or attributed text control?

Use `UITextView` / `NSTextView` when you need:

- `NSAttributedString` or advanced `AttributedString` bridging
- Layout inspection or fragment-level queries
- Syntax highlighting or custom rendering
- Inline attachments or custom attachment views
- Rich editing commands, menus, or selection behavior
- Writing Tools coordination beyond basic defaults

### 4. Do you need TextKit 2 specifically?

**Use TextKit 1** (`NSLayoutManager`) when you need:

- Glyph-level access (custom glyph drawing, glyph metrics, `shouldGenerateGlyphs`)
- Multi-page or multi-column layout (multiple text containers)
- Syntax highlighting via temporary attributes (proven, reliable)
- Text tables (`NSTextTable`, macOS)
- Printing with full pagination control

**Use TextKit 2** (`NSTextLayoutManager`) when you need:

- Viewport-based layout for large documents
- Writing Tools full inline experience
- Correct complex-script rendering by default (Arabic, Devanagari, CJK)
- Modern rendering and layout APIs

Neither is "legacy" or "modern" — they solve different problems. TextKit 1 is the right choice for glyph-level work even in a brand-new app.

For the actual TextKit 1 vs 2 choice, launch the **platform-reference** agent.

## Common Decisions

**Chat composer that grows vertically** -> `TextField(axis: .vertical)` first, `UITextView` if you need richer editing behavior.

**Notes editor with rich text** -> `UITextView` on iOS, `NSTextView` on macOS.

**Syntax-highlighted code editor** -> `UITextView` / `NSTextView`. TextKit 1 if you need temporary attributes (proven) or glyph metrics; TextKit 2 if you need viewport performance on very large files.

**Simple settings field** -> `TextField`, `UITextField`, or `NSTextField`.

**Markdown display only** -> `Text` if the supported inline subset is enough; otherwise use TextKit-backed rendering.

**Need AppKit-only document editor features** -> `NSTextView`.

## Related Skills and Agents

- For the full catalog, capabilities tables, and platform-by-platform reference, see [reference.md](reference.md).
- For usage-oriented examples, see [examples.md](examples.md).
- For wrapping `UITextView` or `NSTextView` in SwiftUI, launch the **platform-reference** agent.
- For the TextKit 1 vs 2 decision specifically, use `/skill apple-text-layout-manager-selection`.
- For TextKit 1 vs 2 architecture, launch the **textkit-reference** agent.
- For a migration or performance decision, launch the **platform-reference** agent.
- For debugging weird editor behavior, use `/skill apple-text-textkit-diag`.