Text replacement on macOS lets you type a short abbreviation and have it instantly expand into a longer word, phrase, or even a sentence. This guide shows you how to set it up, how to use it across Apple and third-party apps, and how to fix the most common reasons it stops working.
What Is Text Replacement and How Does It Work?
Text replacement is a built-in macOS feature that automatically substitutes a trigger string (like “brb”) with a longer replacement (like “be right back”). It works system-wide because it operates at the text input level, not inside individual apps. When you type the trigger followed by a space, punctuation, or a line break, macOS swaps it for the replacement text.
The feature is part of the keyboard services in macOS and syncs across Apple devices via iCloud if you have the same Apple ID signed in. It is available on iPhones and iPads too, so a replacement you add on your Mac can appear on your other devices.
How to Set Up Text Replacement on macOS
- Open System Settings (or System Preferences on older macOS versions).
- Click Keyboard.
- Select the Text Replacements tab (or Text on older versions).
- Click the + button to add a new replacement.
- In the Replace field, type the abbreviation you want to use (e.g., “addr”).
- In the With field, type the full text you want to appear (e.g., “123 Main Street, Springfield, IL 62701”).
- Press Return or click Add to save.
You can also import or export a list of replacements as a .plist file using the same settings pane. This is handy if you want to back up your list or move it to another Mac.
How to Use Text Replacement in Apps
Once set up, text replacement works in most apps that use the standard macOS text input system. This includes Apple’s own apps like Mail, Messages, Notes, Pages, and Safari’s address bar. Many third-party apps also support it, including Chrome, Firefox, Slack, and Microsoft Word.
To use it, simply type the abbreviation and then a space, a period, a comma, or hit Return. The replacement happens instantly. For example, if you set “omw” to expand to “On my way!”, typing “omw” and then a space will produce “On my way!”
If an app does not expand your abbreviations, it likely does not use the system text input. Some apps, especially code editors or apps with custom text fields, have their own autocomplete or snippet systems that override or ignore macOS text replacement.
Why Text Replacement Stops Working (and How to Fix It)
If your abbreviations are not expanding, the cause is usually one of these:
- iCloud sync is off or delayed. Check that you are signed in to iCloud on the Mac and that “Sync this Mac” is enabled for iCloud Drive or Keychain (depending on your macOS version). Sometimes toggling iCloud sync off and on again forces a refresh.
- The app you are using does not support it. Try typing in a standard text field like Notes or Messages. If it works there, the app is the problem, not the system.
- You have a conflicting shortcut. If another app or a keyboard shortcut uses the same abbreviation, it may intercept it. Check your app’s preferences for any text expansion or shortcut settings.
- The abbreviation is too short or too common. macOS only expands abbreviations that are at least 2 characters long, and it will not expand if the abbreviation is a common word like “a” or “i”. Try a longer, unique trigger.
- Software glitch. Restart the app you are using, or restart your Mac. This clears temporary issues with the keyboard service.
If none of these work, try deleting the replacement and re-adding it. Also check that “Use the F1, F2, etc. keys as standard function keys” is not enabled in Keyboard settings, as that can interfere with some key combinations.
Text Replacement vs. Third-Party Tools
macOS’s built-in text replacement is free and simple, but it has limits: it only works in apps that use the standard text input, and it does not support variables, scripts, or formatting. If you need more power, third-party tools like TextExpander or aText offer features like:
- Fill-in-the-blank fields for dynamic content.
- Date and time insertion.
- Image and file insertion.
- Cross-platform support (Windows, Linux, etc.).
These tools are not free, but they provide much more flexibility. For most users, the built-in feature is sufficient for common phrases, email signatures, and addresses.
Common Misconceptions About Text Replacement
One common misconception is that text replacement works in every text field, including password fields and code editors. In reality, macOS disables it in secure fields (like password entry) and in apps that use custom text rendering. Another misconception is that it is case-sensitive. By default, macOS treats abbreviations as case-insensitive, so “brb” and “BRB” both expand. However, the replacement text is inserted exactly as you typed it in the “With” field.
Also, text replacement does not work in the middle of a word. If you type “abc” as part of a longer word, it will not expand. It only triggers when the abbreviation is a separate word, preceded by a space or start of line, and followed by a delimiter.
Frequently Asked Questions
Why is my text replacement not working on my Mac?
The most common reasons are iCloud sync issues, app incompatibility, or a too-common abbreviation. First, test in a native Apple app like Notes. If it works there, the problem is app-specific. If it doesn’t, check your iCloud settings and restart your Mac.
Can I sync text replacements between my Mac and iPhone?
Yes, if you are signed in to the same Apple ID on both devices and have iCloud enabled for keyboard. On your iPhone, go to Settings > General > Keyboard > Text Replacement and you should see the same list. If not, toggle iCloud Drive off and on.
Does text replacement work in all apps?
No. It works in apps that use the standard macOS text input system. Some apps, particularly code editors, IDEs, and apps with custom text fields, may ignore it. For those, you may need a third-party tool or a built-in snippet feature.
How do I delete a text replacement?
Go to System Settings > Keyboard > Text Replacements, select the entry you want to remove, and click the minus button. The deletion will sync to your other devices if iCloud is enabled.
Can I use text replacement for passwords?
No, macOS intentionally disables text replacement in secure text fields to prevent accidental exposure of sensitive information. Use a password manager instead.
Why does my abbreviation expand only sometimes?
This usually happens when the abbreviation is part of a larger word or when the app has its own autocomplete that interferes. Make sure you type the abbreviation as a standalone word, and check if the app has a custom text expansion setting that overrides the system one.
Related
General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.
More in this bed
- How to Enable Privacy Indicators on Chromebook
- How to Calculate Taxes on Overtime Pay
- VPN Not Working on iPhone? Fixes That Actually Work
- Hide & Unhide Apps on Samsung Phones
- Fix DNS Server Unavailable Error in Windows 11
- Fix iOS 17 Keyboard Not Working Properly