What Is Text Replacement? Definition and How It Works on Mac

Text replacement (also called text expansion) is a feature that automatically substitutes a short abbreviation for a longer phrase when you type it. On Mac, it is built into System Settings under Keyboard > Text Replacements. Type ";;addr" and get your full address. The replacement happens when you press Space after the trigger. Users with well-configured text replacements save an average of 5-8 minutes per day on repetitive typing.

How do text replacements work on Mac?

macOS text replacements rely on the NSTextView framework, which is the foundation of text input in native macOS apps. When you type a sequence of characters followed by Space or Return, NSTextView checks whether the typed string matches any trigger in your text replacements list. If a match exists, it deletes the trigger and inserts the replacement phrase in its place.

The system is straightforward by design. Each replacement consists of exactly two fields: the trigger (what you type) and the replacement (what appears). There is no scripting, no conditional logic, and no variable insertion. The substitution is a literal string swap.

Text replacements sync across your Apple devices via iCloud when iCloud Keyboard settings are enabled. An entry created on Mac appears on iPhone and iPad automatically, which is particularly useful for abbreviations you use across contexts - email signatures, company names, phone numbers.

A practical convention many power users adopt is prefixing triggers with a character that never appears in normal words, such as ";;" or "\\". This prevents accidental firing. ";;addr" will never appear in legitimate prose; "addr" might. The typical knowledge worker types their own name 25+ times per day - a single text replacement for ";;name" eliminates all of them.

What's the difference between text replacement and autocorrect?

Text replacement and autocorrect are both triggered typing features, but they work in opposite directions and serve different purposes.

Autocorrect is reactive. It monitors what you type, detects errors compared to a dictionary, and fixes mistakes you made unintentionally. You do not set it up; the system handles it based on its model of what you probably meant to type.

Text replacement is proactive. You explicitly define which abbreviations expand to which phrases. The system does not decide anything - it only matches your predefined triggers. It has no concept of errors; it simply expands what you ask it to expand, every time, without exception.

The practical distinction: autocorrect fixes unintended input; text replacement expands intended input. Using both together covers complementary ground. Autocorrect handles the words you type carelessly; text replacements handle the phrases you type deliberately but want to enter faster.

There is no overlap in terms of the underlying mechanism. Autocorrect uses dictionary lookup and language models; text replacement uses a simple key-value lookup with no language understanding involved.

What are the limitations of text replacements on Mac?

The most significant limitation of macOS text replacements is Electron app incompatibility. Slack, VS Code, Discord, Notion (desktop), and dozens of other popular apps are built on Electron, which renders text using Chromium's text engine rather than Apple's NSTextView. Because text replacements hook into NSTextView, they are never triggered inside Electron apps.

This is not a bug or a configuration problem - it is an architectural constraint. The apps do not use the part of macOS that performs text replacements. No setting change will make them work in Slack or VS Code.

A second limitation is the lack of dynamic content. macOS text replacements insert literal strings only. You cannot create a trigger that inserts today's date, a calculated value, or context-sensitive text. Dedicated text expansion apps like Typinator or Keyboard Maestro fill this gap, but they require additional purchase and setup.

The third limitation is length and formatting. macOS text replacements handle plain text well, but rich text formatting (bold, links, line breaks) is inconsistently supported and varies by app. For formatted snippets, a dedicated expansion tool handles this more reliably.

A fourth consideration is discovery. Text replacements only fire for phrases you have explicitly defined in advance. They require upfront investment to configure and regular maintenance as your vocabulary of reused phrases grows. This is fundamentally different from word prediction, which works without any setup.

How does Charm complement text replacements?

Charm and macOS text replacements address adjacent but non-overlapping problems, and they work well together.

Text replacements handle phrases you know you will type repeatedly and can define in advance. They are deterministic and instant. If you send the same three-sentence response to support inquiries fifty times a week, a text replacement is the right tool.

Charm's Oracle feature handles phrases you did not predict in advance. Oracle reads up to 100 characters of preceding context and suggests the next word based on language model probability. It covers the contextual, spontaneous writing that text replacements cannot anticipate - the sentence that flows naturally from the one you just finished, the word that completes a phrase you did not plan to write.

The two features also complement each other in terms of coverage. Text replacements work only in native macOS apps (not Electron). Charm works everywhere via the Accessibility API, including Slack, VS Code, and Discord. This makes Charm particularly valuable for users who rely on Electron apps professionally: they can pair well-configured text replacements for native apps with Charm's full feature set for the rest of their workflow.

Frequently asked questions

What are text replacements on Mac?

Text replacements are user-defined abbreviation-to-phrase substitutions managed in System Settings under Keyboard > Text Replacements. Type a short trigger, press Space, and macOS replaces it with your predefined full phrase. They sync across Apple devices via iCloud.

How do I set up text replacements on Mac?

Open System Settings, go to Keyboard, and click Edit next to Text Replacements. Click the plus button, enter your abbreviation in the Replace column and your expansion in the With column. The trigger fires on Space or Return in any compatible native macOS app.

Why don't text replacements work in Slack?

Slack, VS Code, and Discord use Chromium's text engine via Electron rather than Apple's NSTextView. macOS text replacements hook into NSTextView exclusively. Electron apps never receive the substitution signal, so text replacements cannot fire in them regardless of settings.

What is the difference between text replacement and word prediction?

Text replacement expands abbreviations you defined in advance - no language model, no context, just a key-value swap. Word prediction suggests the next word contextually based on language model probability, with no setup required. They are complementary: text replacements handle fixed phrases, word prediction handles everything else.

Are text replacements private?

Yes. Substitutions happen on-device with no network request. Your replacement list syncs via iCloud if enabled, so it is as private as your iCloud account. Unlike cloud-based writing tools, no text leaves your device at the moment of replacement.