Draft:Caret affinity

• Comment: sources are not verifiable. Theroadislong (talk) 22:21, 4 May 2026 (UTC)

• Comment: 1 ~2026-27189-92 (talk) 19:09, 4 May 2026 (UTC)

---

In computer graphics and text editing, caret affinity (also known as text affinity or cursor affinity) is a property of the text insertion point (caret) that determines its visual position when a single logical index in a text string corresponds to two different visual locations on the screen.

It is a critical component of text layout engines, ensuring that user interactions such as clicking, typing, and navigating with arrow keys behave predictably at boundaries such as line wraps or changes in text direction.

Background

In a simple text string, a "caret" or "cursor" is logically positioned at an integer offset (index) between two characters. For example, in the string "ABC", an index of 1 represents the gap between A and B. In most cases, this maps to exactly one x,y coordinate on the display.

However, certain layout conditions create a "one-to-many" mapping between the logical index and the visual position:

   Soft line breaks: When a word-processor wraps a line of text, the index at the end of the first line and the beginning of the second line are the same.

   Bidirectional (BiDi) text: At the boundary between Left-to-Right (LTR) and Right-to-Left (RTL) text (e.g., English next to Arabic), the logical sequence of characters may be visually "split" across different parts of a line.

Types of affinity

Affinity is typically implemented as a binary choice:

   Upstream (or Backward): The caret is drawn at the visual position associated with the character preceding the index. In a wrapped line, this would be the end of the upper line.

   Downstream (or Forward): The caret is drawn at the visual position associated with the character following the index. In a wrapped line, this would be the start of the lower line.

Applications

Line wrapping

When a user reaches the end of a line while typing, the layout engine must decide whether to show the blinking caret at the end of the current line or the beginning of the next. Modern editors often use affinity to "stick" the caret to the end of the line if the user clicked there, but move it to the start of the next line if the user is actively typing or used the right-arrow key to cross the boundary.

Bidirectional text

In bidirectional text, affinity resolves ambiguity at the "junction" where text directions flip. A single logical index at the boundary might map to the right edge of an English word and the left edge of a Hebrew word, which could be separated by several inches if they are not at the same visual location. Affinity determines which "side" of the directional boundary the caret favors.

Formatting boundaries

In rich text editors, a caret positioned between a bold word and a regular word (e.g., Bold|Regular) has an "affinity" for the formatting. If the affinity is upstream, the next character typed will be bold; if downstream, it will be regular. Some specialized editors, such as the Bike outliner, use a "dual caret" or distinct visual indicators to show exactly where the affinity lies within the document's markup tree.

Implementation in software APIs

Most major operating systems and UI frameworks provide explicit enums or properties to handle affinity:

   Microsoft Windows: The TextAffinity enum is used in the Text Services Framework and modern UI libraries like Flutter to disambiguate TextPosition.

   Apple macOS/iOS: The NSSelectionAffinity enum (part of TextKit) allows developers to specify if the selection "clings" to the preceding or following character.

   Web Browsers: The Chromium engine uses a CaretWithTextAffinityUpstream flag to manage caret placement during text selection and editing.

See also

TBD:

   Caret (computing)

   Bidirectional text

   Word wrap

   Text editor

References

   "Reusing Previous Computations: Text Editing." Web Browser Engineering. (Explains caret affinity in the context of building a layout engine).

   Microsoft Documentation. "TextAffinity Enum." Windows App Development.

   Apple Developer Documentation. "NSSelectionAffinity." AppKit/UIKit.

   Chromium Source Code. "runtime_enabled_features.json5" (Defining CaretWithTextAffinityUpstream).