Text annotation.

Text annotations support strategy notes and visual callouts while reusing component origins, movement, reset, visibility, and events. Text is rendered with textContent and never interpreted as HTML.

type: "annotation"component: annotation:textClient placement

Usage

Add the text annotation to a graphic.

Add the primitive with view.setAnnotations. Its image-pixel position, content, and presentation are entirely client-authored and do not invoke the protected overlay service.

view.setAnnotations([
  {
    type: "annotation",
    id: "strategy-note",
    position: { x: 520, y: 480 },
    content: {
      type: "text",
      text: "Favor the left side",
      color: "#F7FBF6",
      backgroundColor: "#07110D",
    },
  },
]);

Defaults

Built-in presentation.

Placement sourceClient image pixel

Origincenter

Size48px component box

NetworkNo request

Component options

Configure behavior and presentation.

Option	Type	Default	Description
type	"annotation"	Required	Identifies a client-authored Annotation primitive.
id	string	Required	Stable 1–64 character local identity using letters, numbers, underscores, or hyphens.
position	{ x: number; y: number }	Required	Starting position in pixels within the rendered image. This value is supplied by the client, not the sidecar.
movable	boolean	false	Enables the same pointer and keyboard movement behavior used by Smart Components.
origin	GraphicOverlayOrigin	"center"	Selects which of nine component origins is aligned to the client-provided pixel.
style.size	number	44 or 48	Component box size in CSS pixels, from 20 through 96.
style.label	string \| boolean \| null	null	Optional label using the shared label renderer.
style.labelPosition	GraphicOverlayLabelPosition	"bottom"	One of eight label positions around the component.
style.labelGap	number	6	Whole CSS pixels from 0 through 32 between the component and label.
content.type	"text"	Required	Selects the text primitive renderer.
content.text	string	Required	One to 120 printable characters rendered as safe text.
content.color	#RRGGBB	"#F7FBF6"	Text color.
content.backgroundColor	#RRGGBB	"#07110D"	Text-block background color.

Behavior

Important implementation details.

Text content is assigned through textContent, preventing it from becoming executable markup.
The component box anchors the text; use an origin to choose which point aligns to the requested pixel.
Use a label only when the text block itself needs a second accessible or visual caption.

Local annotation boundaryAnnotations accept client-provided image pixels only. They do not accept longitude, latitude, geometry, transforms, or sidecar data.