Skip to main content

Text expansion

Text expansion replaces a short piece of typed text with something longer. Type btw and a space, and the program you type into receives "by the way" and the space. It works in any program that takes typed text.

The Text expansion page lists the replacements of one app group at a time. Each replacement is an ordinary action whose only trigger is a typed text. It can type or paste text, or run steps, a script or AutoHotkey. An action is listed on the Actions page instead when it has other triggers as well, is limited to profiles (Advanced mode), or runs in a script language a plugin adds; there the typed text is under + Text expansion in its Triggers card. Both follow the rules on this page.

Add a replacement​

Input.ObserverSimpleAdvanced
AUTOMATION
Actions
Text expansion
Autocorrect
Snippets
Recorder
Sandbox
App groups
Ignore groups
Gestures
ENGINE
Global events
Exclusion zones
Scripts
Plugins
SETUP
General
Appearance
Profiles
Console
Security
Help
About
Replacements
By the way
btw
Address
;addr
Text expansion
ReplacementsSettings
App group
Global
Trigger
Typed text
btw
Type the key that ended it
Follow capitalization
What it does
Text
Replacement text
Insert cursor position
by the way
  1. In App group ①, choose where the replacement works. Global works in every program that no other app group claims, and in groups that fall back to Global.
  2. Click + New at the bottom of the Replacements list ②. A replacement named New replacement appears; rename it in its Name box.
  3. In Typed text ③, type the abbreviation, for example btw.
  4. Choose the type ④ (Types).
  5. Enter the Replacement text ⑤, or for RTF and HTML, copy the content in another program and click Paste from clipboard. For Steps, Script and AutoHotkey, the editor for that type appears in its own card below.
  6. Save.

With All chosen in App group, the list shows every group's replacements under the group's name, and a new replacement can't be created until you choose a group.

The Note box beside Category is for your own reference; nothing shows it while you type.

How typed text is matched​

The engine remembers the characters you type since the last boundary or reset. When you type a boundary, it compares what it remembered with every typed-text trigger:

  • The whole word must match. What you typed since the last boundary must equal the typed text exactly, from its first character. btw doesn't expand inside abtw or concatbtw.
  • Case-sensitive, unless the replacement follows capitalization (Capitalization). btw doesn't expand BTW or Btw.
  • Shift is fine. Holding Shift to type a capital or a symbol is ordinary typing.
  • Corrections don't count. Backspace clears what was remembered. If you type bt, press Backspace and type tw, the engine remembers only tw.
You typeTyped textResult
btw Spacebtw"by the way" and a space
btw.btw"by the way."
abtw SpacebtwNothing: the word is abtw.
BTW SpacebtwNothing: different case (unless it follows capitalization).
;addr Enter;addrThe address, then Enter.

The typed text can start or end with characters such as ; : ' " and brackets, which are not boundaries. A leading ; is a common way to keep abbreviations apart from real words.

Capitalization​

Follow capitalization (under Typed text, for the Text and Text via clipboard types) makes a replacement work for two more ways of typing it, and capitalizes the replacement the same way. With adm for "administrator":

You typeResult
admadministrator
AdmAdministrator: the first letter is capitalized, the rest is left as it is.
ADMADMINISTRATOR
aDmNothing: only these three forms expand.

"First letter" means the first character that has a capital form, so ;adm also expands as ;Adm and ;ADM. Capitals follow the rules of your Windows language and region settings.

Changing the type to anything else turns Follow capitalization off. A replacement of another type that has it on anyway (from a configuration file edited by hand, for example) shows it with a note: the capitalized forms still run the replacement, but only Text and Text via clipboard change its capitalization. Turn it off there.

When a typed text is a replacement's own typed text, that replacement runs, even if it is also a capitalized form of another one. So Adm for "Admin console" can sit beside adm with Follow capitalization: typing Adm gives "Admin console", and ADM still gives "ADMINISTRATOR". Two replacements that both follow capitalization and share a form, such as adm and Adm, both expand ADM; the one higher in the list wins, and the page warns about it.

What ends the typed text​

These keys end the typed text and make it expand when it matches:

  • Space, Tab and Enter, each while its switch is on in the Settings tab (all on by default).
  • Period, comma, exclamation mark and question mark: . , ! ?, the Arabic comma, question mark and full stop, and the ideographic and full-width comma, full stop, exclamation mark and question mark, while Expand on punctuation is on (on by default). Off, they are ordinary characters, so a typed text can contain them, such as e.g.

Typed text that contains a boundary can never expand. The page says so under Typed text: This never expands, with the reason (a space while Space is a boundary, a control character, or one of the punctuation marks above while punctuation is a boundary).

What clears the typed text​

The remembered characters are thrown away, and you start a new word, when:

  • you press Backspace, Escape, Delete, an arrow key, Home, End, Page Up, Page Down or a function key, or any key that doesn't type a character;
  • you press any key while Ctrl, Alt or Win is held. A shortcut is never typing, so Alt+Tab or Ctrl+Enter right after an abbreviation never expands it;
  • you click any mouse button;
  • you switch to another window, or the keyboard focus moves to another field that is a window of its own;
  • a script types or presses keys;
  • you type more characters than the longest typed text you have set up, without a boundary.

Focus moving between fields inside one window, as on a web page, doesn't clear them unless you turn on Start over when focus moves inside a window on the Settings tab. It is off by default because the suggestion lists of address bars move that focus on nearly every keystroke as you type. The same setting applies to autocorrect. An editor's own completion list, such as Notepad++'s, never clears them: the keys still go to the editor.

What happens when it expands​

When a boundary completes a typed text that has a replacement for the window in front:

  1. The boundary key is held back from the program for now.
  2. The typed text is erased with one Backspace per character.
  3. The replacement goes in.
  4. The boundary key goes in right after the replacement, while Type the key that ended it is on (the default). An Enter or Tab boundary therefore acts on the finished text: a chat program sends the replaced message, and a form moves to the next field only after the text is complete. Off, the key only makes the text expand and is never typed: btw Space gives "by the way" with no space.

Keys you type while this happens are held and typed afterwards, in order, so they can't land in the middle of the replacement. If the replacement takes long to start (more than half a second with nothing sent) or holds keys for 10 seconds in all, the held keys are let go.

Typing is paced by Typing delay on the Scripts page (Advanced mode; default 30 ms between keystrokes). Some programs, such as Notepad on Windows 11, scramble text that arrives with no pause (Scripts settings).

Types​

TypeWhat it doesUse it for
TextTypes the replacement as keystrokes.Short text. Works almost everywhere; long text takes a moment to type.
Text via clipboardPuts the text on the clipboard and pastes it with Ctrl+V.Long text and text with line breaks. Instant.
RTFPastes formatted text (Rich Text Format).Formatting in word processors and mail programs.
HTMLPastes an HTML fragment.Formatting in browsers, web mail and editors that take HTML.
StepsRuns steps, edited as on the Actions page (Steps).Anything a few steps do: press keys, type text in parts, work with windows.
ScriptRuns a script, edited as on the Actions page.Text worked out when you type it, such as today's date in your own format.
AutoHotkeyRuns an AutoHotkey v2 script (Action engines).An AutoHotkey script you already have. Offered while AutoHotkey is turned on in General settings, or when the replacement already uses it.

For RTF and HTML, Paste from clipboard stores exactly what you copied: copy the formatted content in another program first. The page shows a Preview. The HTML preview needs the Microsoft Edge WebView2 runtime; without it the page says so, and the replacement still works. RTF source typed by hand can use any character directly; it is written as RTF's own \u escape for you. RTF and HTML replacements also put a plain-text copy on the clipboard, so a program that only takes plain text pastes the words.

Changing the type keeps what you had while the configuration window is open: steps of your own come back when you switch to Steps again, even after a look at Script, AutoHotkey or one of the text types, and the Script and AutoHotkey text stay as they are. Once the window closes, only what was saved is left: a replacement saved as Text or another text type keeps no steps of your own. While the Script text is still empty, switching to Script from Text or Steps offers to turn the replacement into a script. A Steps replacement whose steps are exactly what Text or a clipboard type would make opens as that type the next time you select it.

For Steps, Script and AutoHotkey, the card warns when the chosen type has nothing to run but another one does, and its button switches the type to the one that does.

Cursor position​

In Text and Text via clipboard, $|$ in the replacement marks where the cursor ends up. Insert cursor position puts it where the cursor is in the box. With Dear $|$, the replacement types "Dear ," and moves the cursor back between the space and the comma, ready for the name.

  • The cursor is moved with the Left arrow key, once per character after the mark. A line break, an emoji (also one built from several, such as a flag, a family or one with a skin tone) and a letter with accents count as one character each.
  • Only the first $|$ counts. Any later one is typed as it is, and the page warns about it.
  • At most 10,000 characters can follow the mark. With more, the $|$ doesn't move the cursor and is typed as it is, and the page warns about it.
  • While the replacement has a cursor position, Type the key that ended it is off and greyed out: the key would otherwise land where the cursor ends up. This holds for the Steps or Script the replacement turns into when you change its type, as long as they still press the arrow key after the text. If the key is on anyway, the page warns, and you can turn it off.
  • A $|$ at the very end moves nothing; it only stops the ending key being typed, and it isn't kept in the replacement.

In a field where the text runs right to left, such as Arabic or Hebrew, the Left arrow key moves the cursor forward through the text, so the cursor would end up in the wrong place. For such a field, turn on Text runs right to left, shown under the text box while the replacement has a cursor position: the cursor is then moved with the Right arrow key instead. The setting belongs to the replacement, since Input.Observer can't tell which way a field runs.

Restore the clipboard​

The three clipboard types replace what is on the clipboard. Restore the clipboard afterwards (on by default) saves the clipboard first and puts it back after the paste. In Advanced mode, Wait before restoring (ms) (default 150, 0 to 60,000) gives the program time to finish pasting first. If a program pastes your old clipboard content instead of the replacement, increase it. A cursor position moves the cursor right after the paste, before the wait.

note

Advanced mode. Wait before restoring (ms) is shown in Advanced mode only.

Which replacement runs​

A typed text has no window under the pointer. It uses the window in front at the moment you type the boundary:

  1. If the window belongs to an ignore group, nothing expands, and the boundary key reaches the program normally.
  2. Otherwise the window's app group is tried first, if it applies in the active profile. Within the group, an enabled replacement or action whose own typed text is exactly what you typed runs first; only then is a capitalized form of one that follows capitalization tried. When two have the same typed text, or share a capitalized form, the one higher in the list runs; the page warns about it. Move up and Move down change the order.
  3. If the group has nothing for it, the Global group is tried, unless Fall back to Global is off for the group or on the General page (Scope and fallback).
  4. If nothing matches, nothing happens: the boundary key reaches the program as you typed it.

Gestures work here and Hotkeys work here on an app group don't affect text expansion.

Autocorrect also acts when you finish typing a word. When the same key completes a typed text that has a replacement or action for the window in front, text expansion wins: it runs, and the word isn't corrected. The Autocorrect page marks a typo that is also an enabled typed text. Text expansion enabled doesn't turn autocorrect on or off, and the autocorrect switch doesn't affect text expansion.

The Settings tab​

When to expand
Text expansion enabled
Expands typed text as you type: the replacements on this page and every action with a typed-text trigger. Off, none of them fire, and none are changed.
Expand on Space
Expand on Tab
Expand on Enter
Expand on punctuation
Start over when focus moves inside a window
  • Text expansion enabled ① turns all text expansion on or off: the replacements on this page and every action with a typed-text trigger. Off, nothing expands and no replacement is changed. While it is off, the Replacements tab shows a notice, and the Actions page flags each typed-text trigger.
  • Expand on Space ②, Expand on Tab and Expand on Enter choose which of the three keys end typed text. They apply to every app group. Turning one off doesn't make the key ignored:
    • With Expand on Space off, a space becomes part of the typed text. A typed text can then contain spaces, such as my addr, and expand on a punctuation mark, Tab or Enter.
    • With Expand on Tab or Expand on Enter off, that key clears the typed text instead, like Backspace.
  • Expand on punctuation ③ makes the period, comma, exclamation mark and question mark (and their Arabic and full-width forms) end typed text. Off, they are part of it, as in StrokesPlus.net, so e.g can be a typed text that expands on Space, Tab or Enter.
  • Start over when focus moves inside a window ④ (off by default) clears the typed text when focus moves to another field of the same window, such as on a web page (What clears the typed text). The same setting applies to autocorrect and is shown on its page too.
note

Advanced mode. Expand on Space, Expand on Tab, Expand on Enter and Expand on punctuation are shown in Advanced mode only. They are greyed out while Text expansion enabled is off.

When text doesn't expand​

  • While the engine is disabled, or paused by Pause everything while focused (Ignore groups), and while a gesture is being drawn.
  • With an input method editor open. With a Japanese, Chinese or Korean input method turned on in the window in front, typed keys are composition input and Space converts it, so nothing expands and the key goes to the input method. Switch it to direct input to expand.
  • Characters typed with AltGr. On layouts where AltGr types a character (such as @ on a German keyboard), Windows reports it as Ctrl+Alt, which clears the typed text. Such characters can't be part of a typed text.
  • Dead keys. A dead key (an accent typed before its letter) clears the typed text, so accented characters composed that way can't be part of it. Characters your layout types with a single key work.
  • Programs that erase differently. The erase sends one Backspace per character. Combined characters and joined emoji count as one character each, and some programs erase them differently, so a typed text built from them may not erase cleanly.