How to set up text replacements on Mac

macOS has a built-in text replacement system that lets you type a short snippet — say ;addr — and have it expand into your full address. It works across Mail, Messages, Notes, Pages, and most system text fields without any extra software.

What text replacements actually do

A text replacement maps a short trigger phrase to a longer expansion. As soon as you type the trigger and press Space or a punctuation mark, macOS swaps it out. Good uses include: full email signatures, recurring phrases you retype constantly, your phone number, boilerplate legal disclaimers, or correcting words you consistently mistype.

The replacements live in your Apple ID account, so they sync to your iPhone and iPad over iCloud automatically — the same list shows up in iOS Settings > General > Keyboard > Text Replacement.

How to add a text replacement

1. Open System Settings (Apple menu, top left).
2. Go to Keyboard, then click Text Replacements… in the top-right corner of the Keyboard panel.
3. Click the + button at the bottom-left of the list.
4. In the Replace column, type your trigger (e.g. ;sig). In the With column, type the expanded text.
5. Press Return to save. The replacement is active immediately.

A tip on triggers: use a prefix character like ; or // that you wouldn't normally type mid-word. That prevents accidental expansions — omw on its own, for instance, will fire whenever you type "omw" inside a longer word.

Using replacements in apps

Type your trigger in any supported app, then press Space, Return, or a punctuation key. macOS replaces the text inline. If it expands when you didn't want it to, press ⌘Z immediately to undo the expansion and keep the original trigger.

Apps that honor text replacements include Mail, Messages, Notes, Pages, Numbers, Keynote, Safari form fields, TextEdit, and most AppKit-based apps. The replacements also work on iPhone and iPad once iCloud sync kicks in (usually within seconds).

Where replacements are stored

macOS stores your replacements inside ~/Library/Preferences/.GlobalPreferences.plist under the NSUserDictionaryReplacementItems key. Unlike many macOS hidden settings, there is no clean defaults write command for adding individual entries — the plist uses an array structure that is awkward to edit from the command line. The System Settings UI is the right tool here.

If you need to back up or transfer replacements, you can export the relevant key with:

# read your current replacement list
defaults read -g NSUserDictionaryReplacementItems

This prints the array to the terminal. Restoring it on a new Mac requires writing the full array back, which is fiddly. For most people, iCloud sync is a simpler option.

Limitations worth knowing

Text replacements do not work everywhere. The most common gaps:

• Terminal — completely ignored. Terminal handles its own input and bypasses the macOS text input system.
• Electron apps — VS Code, Slack, Discord, Notion, and other Electron-based apps often do not fire macOS text replacements. Some have built-in snippet systems; others don't.
• Web browsers — Chrome and Firefox generally don't honor them in text fields. Safari does.
• Multi-line expansions — the built-in system handles simple single-paragraph expansions well, but complex formatting (rich text, line breaks, variables) is beyond its scope.

Free alternatives when the built-in system isn't enough

If you hit those limits regularly, two free tools are worth trying.

Espanso is open-source, works in every app including Terminal and VS Code, and stores snippets as plain YAML files you can version-control. It runs as a background process and is highly configurable — you can add variables, dynamic date insertion, and cursor positioning. Install it via Homebrew: brew install espanso.

Raycast includes a Snippets feature (free tier) that fires via its own hotkey and also supports global expansion in most apps. If you already use Raycast as a launcher, the snippets live in the same place.

For light use — your address, a few email phrases — the macOS built-in system is completely adequate. For power users who want expansions everywhere, Espanso is the most capable free option.

Editing and deleting replacements

In System Settings > Keyboard > Text Replacements, double-click any entry to edit it in place. To delete one, select it and press the − button, or hit the Delete key. Changes sync to iCloud immediately.

There's no bulk import UI, but if you're migrating from another Mac where iCloud was connected, the list transfers automatically when you sign in with the same Apple ID.