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 with a typed-text trigger. An action that does something else when you type text (runs a script, presses keys, has other triggers) is listed on the Actions page instead, under + Text expansion in its Triggers card. Both follow the rules on this page.

Add a replacement

Input.ObserverSimpleAdvanced

AUTOMATION

Actions

Text expansion

Snippets

Recorder

Sandbox

App groups

Ignore groups

Gestures

ENGINE

Global events

Exclusion zones

Scripts

Plugins

SETUP

General

Appearance

Profiles

Console

Security

Help

About

2

Replacements

By the way

btw

Address

;addr

Text expansion

ReplacementsSettings

App group

1Global

Trigger

Typed text

3btw

Case-sensitive. Expands when followed by Space, Tab or Enter, or by a period, comma, exclamation mark or question mark.

What it does

4TextText via clipboardRTFHTML

Replacement text

5by 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.
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.

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. btw doesn't expand BTW or Btw. Add a second replacement for each form you want.
• 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 type	Typed text	Result
btw Space	btw	"by the way" and a space
btw.	btw	"by the way."
abtw Space	btw	Nothing: the word is abtw.
BTW Space	btw	Nothing: different case.
;addr Enter	;addr	The 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.

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. These always end it.

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).

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;
• a script types or presses keys;
• you type more characters than the longest typed text you have set up, without a boundary.

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. 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.

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

Type	What it does	Use it for
Text	Types the replacement as keystrokes.	Short text. Works almost everywhere; long text takes a moment to type.
Text via clipboard	Puts the text on the clipboard and pastes it with Ctrl+V.	Long text and text with line breaks. Instant.
RTF	Pastes formatted text (Rich Text Format).	Formatting in word processors and mail programs.
HTML	Pastes an HTML fragment.	Formatting in browsers, web mail and editors that take HTML.

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.

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) gives the program time to finish pasting first. If a program pastes your old clipboard content instead of the replacement, increase it.

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, the first enabled replacement or action with exactly this typed text runs. When two have the same typed text, 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.

The Settings tab

When to expand

1

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.

2

Expand on Space

Expand on Tab

Expand on Enter

• 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.

note

Advanced mode. Expand on Space, Expand on Tab and Expand on Enter 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.