Skip to content
Apple Text
Docs
Apple Text Views

Apple Text Views

Use when the main task is choosing the right Apple text view or deciding whether a problem belongs in SwiftUI text, UIKit/AppKit text views, or TextKit mode. Reach for this when comparing capabilities and tradeoffs, not when implementing a specific wrapper or low-level API.

Decision Skills

Use when the main task is choosing the right Apple text view or deciding whether a problem belongs in SwiftUI text, UIKit/AppKit text views, or TextKit mode. Reach for this when comparing capabilities and tradeoffs, not when implementing a specific wrapper or low-level API.

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

Section titled “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

Section titled “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

Section titled “Core Guidance”

Decision Guide

Section titled “Decision Guide”

1. Are you editing text?

Section titled “1. Are you editing text?”

No -> Prefer Text or UILabel.

Yes -> Go to step 2.

2. Is plain-text SwiftUI editing enough?

Section titled “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?

Section titled “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?

Section titled “4. Do you need TextKit 2 specifically?”

Prefer TextKit 2 when you need:

  • Viewport-based layout
  • NSTextLayoutManager
  • Writing Tools inline behavior
  • Modern rendering and layout APIs

Stay on TextKit 1 when you explicitly need:

  • Glyph APIs
  • Mature multi-container patterns
  • Legacy code that depends on NSLayoutManager
  • AppKit features still tied to older APIs

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

Common Decisions

Section titled “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, usually with TextKit 2 if your feature set allows it.

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.

Section titled “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 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

Section titled “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.

Section titled “Related”
  • apple-text: Use when the user clearly has an Apple text-system problem but the right specialist skill is not obvious yet, or when the request mixes TextKit, text views, storage, layout, parsing, and Writing Tools. Reach for this router when you need the next best Apple-text skill, not when the subsystem is already clear.
  • apple-text-representable: Use when embedding UITextView or NSTextView inside SwiftUI and the hard part is wrapper behavior: two-way binding, focus, sizing, cursor preservation, update loops, toolbars, or environment bridging. Reach for this when native SwiftUI text views are not enough, not when choosing between text stacks at a high level.
  • apple-text-layout-manager-selection: Use when the main task is choosing between TextKit 1 and TextKit 2, especially NSLayoutManager versus NSTextLayoutManager for performance, migration risk, large documents, or feature fit. Reach for this when the stack choice is still open, not when the user already needs API-level mechanics.

Sidecar Files

Section titled “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 the main task is choosing the right Apple text view or deciding whether a problem belongs in SwiftUI text, UIKit/AppKit text views, or TextKit mode. Reach for this when comparing capabilities and tradeoffs, not when implementing a specific wrapper or low-level API.
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?


Prefer TextKit 2 when you need:


- Viewport-based layout
- `NSTextLayoutManager`
- Writing Tools inline behavior
- Modern rendering and layout APIs


Stay on TextKit 1 when you explicitly need:


- Glyph APIs
- Mature multi-container patterns
- Legacy code that depends on `NSLayoutManager`
- AppKit features still tied to older APIs


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`, usually with TextKit 2 if your feature set allows it.


**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 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`.
Apple Text docs for TextKit, Apple text views, and Writing Tools. Source on GitHub.
Home Docs GitHub

Start Here

Overview Setup Commands Agents Examples

Guide

Overview Quick Start MCP Server Xcode Integration Install Entry Points Routing Model Problem Routing Commands And Agents

Skills

Overview