Writing Tools API: How Apps Plug Into Apple Intelligence's Writing Layer

Apple Intelligence’s writing layer, branded Writing Tools, ships in every iOS 18+ device with Apple Intelligence enabled. The user selects text, taps the Writing Tools menu, and gets proofreading, rewriting (friendly, professional, concise), summarization, list and table generation, and (since iOS 18.2) generative composition¹. The capability lives at the system layer, not in any one app, and the user expects it to work in every text input.

Apps that use UITextView, NSTextView, or WKWebView get the integration without writing code, provided the text view runs on TextKit 2². Apps with custom text engines need the UIWritingToolsCoordinator API to plug their text storage and rendering into the Writing Tools experience. The post walks the API surface against Apple’s documentation, names the three adoption tiers, and covers when to opt out (because not every text input should accept generative rewrites).

TL;DR

• Standard text views (UITextView, NSTextView, WKWebView) on TextKit 2 get Writing Tools for free, with the full inline-rewrite-with-animation experience².
• Custom text views adopt UITextInteraction to get the callout/context menu integration without further code; full inline integration requires the UIWritingToolsCoordinator API³.
• UIWritingToolsBehavior is a single enum property that controls the experience tier: .complete, .limited, or .none⁴. The .default value is a request the system resolves at runtime to one of those three; it’s not a fourth tier. For sensitive text (passwords, source code editors, chat fields users don’t want rewritten), set .none.
• allowedWritingToolsResultOptions lets apps declare which output shapes they accept (plain text, rich text, lists, tables, or .presentationIntent in iOS 26) so Writing Tools does not return content the app cannot render⁵.
• The agent-workflow tie-in: Writing Tools is an Apple Intelligence surface like App Intents and Foundation Models, but operates at the text-input layer rather than the action layer.

What Writing Tools Actually Does

The Writing Tools menu in iOS 18+ exposes a set of operations on selected text. The current public set, per Apple’s developer documentation and the WWDC 2024 introduction⁶:

Proofread. Fixes grammar, spelling, punctuation, and word choice. Returns a diff the user can accept, reject, or step through.

Rewrite. Three preset tones (friendly, professional, concise) plus a “describe your change” custom prompt. The model rewrites the selected text in the chosen tone.

Summarize. Long text becomes short. Variants include “summary,” “key points,” “list,” “table.” The user picks the shape.

Compose. Generative writing from a prompt (iOS 18.2+). The user describes what they want; the model generates new text rather than rewriting existing text.

The model running Writing Tools is Apple’s on-device foundation model on supported hardware, with a private-cloud fallback for larger requests¹. The user’s text does not go to a third party, ever. The privacy story is part of the value proposition.

The Three Adoption Tiers

Apps fall into one of three buckets based on how much Writing Tools integration they need.

Tier 1: Standard Text View (Zero Code)

Apps that use UITextView, NSTextView, or WKWebView for text input get Writing Tools without writing any code, provided the text view uses TextKit 2². The system handles the menu, the inline rewrite UI, the animation, and the proofreading inline highlights. The app’s job is to use the standard text view.

let textView = UITextView()
textView.text = "Original content."
textView.isEditable = true
// Writing Tools just works.

The TextKit 2 requirement matters because TextKit 1 ships with a different layout architecture that does not support the inline-rewrite animation. New apps targeting iOS 18+ should default to TextKit 2; legacy apps may need a migration step. UITextView defaults to TextKit 2 on iOS 16+ when initialized through Interface Builder or the modern initializer.

Tier 2: Custom Text View with UITextInteraction (Callout Only)

Apps with custom text views can adopt UITextInteraction to get Writing Tools in the callout bar and context menu without further code⁷. The user can invoke Writing Tools, see the panel-style interface for proofread/rewrite/summarize, and accept or reject the result. The result is delivered to the app through the standard paste/replace flow.

The integration is partial: the app does not get the inline animation or the proofreading inline highlights. Those require the full coordinator. For most apps with custom text views, UITextInteraction adoption is enough.

Tier 3: UIWritingToolsCoordinator (Full Inline Experience)

Apps that want the full Writing Tools experience with custom text storage adopt UIWritingToolsCoordinator (or NSWritingToolsCoordinator on macOS)³. The coordinator manages the bidirectional conversation between Writing Tools and the app:

• The app provides text context (an NSAttributedString representing the current selection plus optional surrounding paragraphs) to the coordinator.
• The coordinator manages the panel UI and the inline animation.
• The coordinator calls back through a delegate to insert, replace, or animate text changes in the app’s text storage.

Key delegate methods on UIWritingToolsCoordinator.Delegate, verified against the iOS 26 SDK headers³:

• writingToolsCoordinator(_:requestsContextsForScope:completion:). The intake method. Writing Tools asks the app for the relevant text contexts (each an NSAttributedString plus a selection range) within a given scope. The app builds the contexts from its text storage and returns them.
• writingToolsCoordinator(_:replaceRange:inContext:proposedText:reason:animationParameters:completion:). The workhorse for text changes. Writing Tools proposes new text for a range within a context; the app applies the change to its storage and confirms.
• writingToolsCoordinator(_:finishTextAnimation:forRange:inContext:completion:). Called when a text animation (the morph between original and rewritten text) completes for a range. Not the session-end signal.
• writingToolsCoordinator(_:willChangeToState:completion:). The session-lifecycle signal. The coordinator transitions through states (idle, interactive, noninteractive, etc.) and notifies the delegate before each transition. This is where the app responds to “session starting” and “session ending.”

The coordinator API is designed for serialized text engines (TextKit-style), document-shaped editors, and code editors that want partial integration. Apple’s session “Dive deeper into Writing Tools” at WWDC 2025⁸ walks the multi-paragraph, multi-style cases. Note that UIWritingToolsCoordinator first shipped as public API in iOS 18.2; iOS 26 deepens it rather than introducing it.

The Behavior Property: UIWritingToolsBehavior

The single most important opt-in/opt-out control is the writingToolsBehavior property on UITextView, UITextField, and any view conforming to UITextInputTraits⁴:

textView.writingToolsBehavior = .complete   // full inline experience
textView.writingToolsBehavior = .limited    // panel-only (no inline rewrite)
textView.writingToolsBehavior = .none       // disabled entirely
textView.writingToolsBehavior = .default    // request system default

Three values are real experience tiers; .default is a request that the system resolves to one of the other three based on the text input’s traits:

• .complete. The full Writing Tools experience including inline rewrite animation, inline proofreading highlights, and the panel. Best for long-form text editors (Mail composer, Notes, document editors).
• .limited. The panel-only experience. The user gets Writing Tools in the menu, but rewrites happen in a panel rather than inline. Best for shorter text fields where inline animation would feel disproportionate.
• .none. Writing Tools is disabled for this text input. Use for sensitive content.
• .default. A request, not a tier. The header documents the resolved value as always being one of .none, .limited, or .complete; the read-only behavior property never returns .default. Most apps should leave the property at .default unless there’s a specific reason to override.

When To Opt Out

Three categories of text input where .none is the right call:

Passwords and sensitive credentials. A password field should never offer “rewrite this in a friendly tone” as an option. The user is entering literal text that must not be transformed. Apple’s UITextField with isSecureTextEntry = true already disables Writing Tools by default; explicit .none is belt-and-suspenders.

Source code editors. A SwiftUI code editor or a Markdown editor for technical content is not improved by being asked to rewrite the selected code in a “professional” tone. Writing Tools’ rewrite paths are tuned for natural language, not for syntactic structures. Set .none on text views whose content is not natural language.

Chat fields where rewriting changes intent. A messaging app or a comments field where the user’s exact words matter (for tone, voice, accountability) may want to omit rewrite while keeping proofread. Writing Tools’ current API does not allow per-action gating; the .none value disables the whole experience. The pragmatic move is .limited (panel-only, which the user has to deliberately invoke) for fields where rewrite is occasionally appropriate but should not be the inline default.

allowedWritingToolsResultOptions Declares What Your App Can Render

A subtler control sits on UITextInputTraits.allowedWritingToolsResultOptions (also exposed as UITextView.allowedWritingToolsResultOptions)⁵. The property is a UIWritingToolsResultOptions option set that declares which content shapes the app’s text view can render:

• .plainText. The text view supports plain text (no formatting attributes).
• .richText. Supports formatted text (bold, italic, etc.).
• .list. Supports list rendering (bullets, numbered).
• .table. Supports table rendering.
• .presentationIntent (iOS 26+). Supports rich semantic intent markup (headings, block quotes, code blocks) using the Foundation framework’s PresentationIntent types, which is a richer surface than plain rich text.

When set, Writing Tools constrains its output to shapes the app accepts. A plain-text editor declaring only .plainText will not get a “make this a table” suggestion. A rich-text editor declaring .richText and .list but not .table will get list output but not table output.

The default value is .default, which lets the system pick based on the text view’s traits. Set the property explicitly when the auto-detection produces wrong shapes (a text view that could render rich text but the app’s data model only stores plain).

Where The Output Lands

For Tier 1 apps (standard text views), the output replaces selection inline through the standard text view machinery. No app code is involved.

For Tier 2 apps (custom views with UITextInteraction), the output arrives through the standard paste flow. The text view’s UITextInput protocol implementation is what processes the change. Apps that have correctly implemented UITextInput get the integration “for free” once UITextInteraction is added.

For Tier 3 apps (full coordinator), the output comes through the delegate’s replaceRange: method. The app applies the change to its text storage, returns the new text bounds in the completion handler, and the coordinator handles the visual transition. The app remains the source of truth for text storage.

What WWDC 2025’s Deep Dive Added

The “Dive deeper into Writing Tools” session at WWDC 2025⁸ expanded the iOS 18 API along three axes worth naming:

Multi-paragraph context. Apps can now provide more surrounding context to the coordinator, allowing Writing Tools to operate on selections that depend on surrounding paragraphs (a sentence whose meaning depends on the paragraph above, for example).

Custom rewrite prompts. The “describe your change” path that was iOS 18.2 in beta became fully public, with delegate hooks for apps that want to inspect or transform the user’s prompt before passing it to the model.

Better handling of mixed content. Text selections that span multiple styles or include embedded images now flow through the coordinator with the embedded content preserved as opaque ranges. The coordinator does not attempt to rewrite an inline image; it preserves it and rewrites the surrounding text.

The deltas are extensions of the iOS 18 model rather than a replacement. Apps that adopted iOS 18 Writing Tools APIs continue to work; iOS 26 unlocks deeper integration for apps that need it.

The Agent-Workflow Connection

Writing Tools is one of three Apple Intelligence surfaces a third-party app can integrate with:

Writing Tools. The text-input layer. The user selects text, asks the system to transform it, gets the result inline. Apps participate by exposing well-formed text views and (optionally) implementing the coordinator. The user invokes; the app receives the result.

App Intents. The action layer. The user (or an agent) asks Apple Intelligence to perform an action; the system routes the request to a registered intent in the app. Apps participate by declaring AppIntent types, parameter schemas, and result types. Covered in App Intents Are Apple’s New API to Your App.

Foundation Models. The runtime LLM layer. Apps invoke the on-device LLM directly through the Foundation Models framework for in-app generation. Covered in Foundation Models on-device LLM.

The three surfaces compose. A note-taking app might use Writing Tools (for the user’s selection-based rewrites), App Intents (for “summarize my notes from yesterday”), and Foundation Models (for an in-app generative feature like auto-tagging). Each layer is a distinct integration with a distinct user mental model.

The App Intents vs MCP Tools post covers when to expose an action through App Intents (Apple Intelligence) versus an MCP server (general agents). Writing Tools sits outside that question; it is a system-level surface that does not have a third-party-agent equivalent in the cluster’s coverage.

What This Pattern Means For iOS 26+ Apps

Three takeaways.

1. Default to the standard text views and TextKit 2. Most apps do not need the coordinator API. If the app’s text input is a UITextView or a WKWebView, Writing Tools works without code; the work is in TextKit 2 migration if the app still runs TextKit 1.

2. Set writingToolsBehavior = .none deliberately for sensitive inputs. Passwords, code editors, exact-text fields. The default tries to do the right thing, but the explicit setting is a defensible product decision the team can articulate.

3. Reach for UIWritingToolsCoordinator only when the app’s text engine is genuinely custom. Markdown editors, code editors, document apps with custom rendering, terminal-style text views. The coordinator is real engineering investment; Tier 2 (UITextInteraction) is enough for most custom views.

The full Apple Ecosystem cluster: typed App Intents; MCP servers; the routing question; Foundation Models; the runtime vs tooling LLM distinction; three surfaces; the single source of truth pattern; Two MCP Servers; hooks for Apple development; Live Activities; the watchOS runtime; SwiftUI internals; RealityKit’s spatial mental model; SwiftData schema discipline; Liquid Glass patterns; multi-platform shipping; the platform matrix; Vision framework; Symbol Effects; Core ML inference; what I refuse to write about. The hub is at the Apple Ecosystem Series. For broader iOS-with-AI-agents context, see the iOS Agent Development guide.

FAQ

Do I need Apple Intelligence to test Writing Tools in my app?

To test the full user experience, yes. The user-facing Writing Tools menu only appears on devices that have Apple Intelligence enabled (iPhone 15 Pro or newer, M1 Mac or newer, with iOS 18+ / macOS 15+). For development purposes, you can test the API integration on any iOS 18+ simulator or device by checking that your text view exposes isWritingToolsActive and that delegate methods are wired correctly; the system menu just won’t surface without Apple Intelligence available.

What happens if I do nothing about Writing Tools in my iOS 18+ app?

For standard text views (UITextView, WKWebView), Writing Tools shows up automatically. For custom text views without UITextInteraction, Writing Tools does not appear in the menu and users cannot invoke it on text in your app. Doing nothing is a defensible default for views where Writing Tools would be inappropriate (password fields, code editors); for general text input, doing nothing means missing a system feature users will look for.

What’s the difference between .complete and .limited?

.complete runs Writing Tools rewrites inline with an animation that morphs the original text into the rewrite, plus inline proofreading highlights. .limited runs Writing Tools through a panel UI; the user sees the rewrite in a separate surface and decides whether to apply it. Use .complete for long-form text editors where inline animation reinforces the editing flow; .limited for shorter text fields where the panel feels right.

Can I customize the Writing Tools prompts or model behavior?

The model and prompts are system-controlled. Apps cannot inject custom rewrite behaviors into the Writing Tools menu. For app-specific generative writing features, use the Foundation Models framework directly (covered in Foundation Models on-device LLM) and surface the feature through your own UI.

How does Writing Tools handle mixed selections (text + image)?

Per WWDC 2025’s “Dive deeper into Writing Tools”⁸, mixed selections that include embedded content (images, attachments) flow through the coordinator with the embedded content preserved as opaque ranges. Writing Tools rewrites surrounding text but does not attempt to transform the embedded content. For apps using the coordinator, the delegate receives proposed-text payloads where the embedded content’s range is marked unchanged.

References