> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.doc-detective.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server. # annotation > A visual annotation drawn onto a screenshot or recording. Each annotation names exactly one type (`outline`, `arrow`, `badge`, `callout`, `blur`, or `text`), and the type's value is the target it points at: an element (a selector/display-text string or a detailed find object) or a fixed `position` in the capture. `id`, `track`, `transition`, and `duration` describe behavior over time — they apply to recordings and are inert in still screenshots, so the same annotation means the same thing in both. A visual annotation drawn onto a screenshot or recording. Each annotation names exactly one type (`outline`, `arrow`, `badge`, `callout`, `blur`, or `text`), and the type's value is the target it points at: an element (a selector/display-text string or a detailed find object) or a fixed `position` in the capture. `id`, `track`, `transition`, and `duration` describe behavior over time — they apply to recordings and are inert in still screenshots, so the same annotation means the same thing in both. ## Referenced In * [Capture screenshot (detailed)](/reference/schemas/capture-screenshot-detailed) * [Capture screenshot fields](/reference/schemas/capture-screenshot-fields) * [annotate](/reference/schemas/annotate) * [Annotate fields](/reference/schemas/annotate-fields) ## Fields | Field | Type | Description | Default | | :--------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | | outline | one of: - string - object([Target by element (detailed)](/reference/schemas/target-by-element-detailed)) - object([Target by position](/reference/schemas/target-by-position)) | Optional. Draw a box around the target. | — | | arrow | one of: - string - object([Target by element (detailed)](/reference/schemas/target-by-element-detailed)) - object([Target by position](/reference/schemas/target-by-position)) | Optional. Point an arrow at the target. | — | | badge | one of: - string - object([Target by element (detailed)](/reference/schemas/target-by-element-detailed)) - object([Target by position](/reference/schemas/target-by-position)) | Optional. Mark the target with a small numbered or lettered marker. Set the marker's characters with `label`. | — | | callout | one of: - string - object([Target by element (detailed)](/reference/schemas/target-by-element-detailed)) - object([Target by position](/reference/schemas/target-by-position)) | Optional. Label the target with a text box and a leader line. Set the text with `label`. | — | | blur | one of: - string - object([Target by element (detailed)](/reference/schemas/target-by-element-detailed)) - object([Target by position](/reference/schemas/target-by-position)) | Optional. Obscure the target to redact sensitive information. Pair with `all` to redact every match rather than the first. | — | | text | one of: - string - object([Target by element (detailed)](/reference/schemas/target-by-element-detailed)) - object([Target by position](/reference/schemas/target-by-position)) | Optional. Place a standalone text box. Set the text with `label`. | — | | label | string | Optional. Text to display. Required by `badge`, `callout`, and `text`; ignored by the other types. | — | | id | string | Optional. Handle for this annotation, so a later `annotate` step can update or clear it. Only meaningful for annotations added by an `annotate` step; ignored on screenshot annotations, which live only for the capture. Pattern: `^[A-Za-z0-9_-]+$` | — | | style | object([Annotation style](/reference/schemas/annotation-style)) | Optional. Visual overrides for this annotation. Anything unset falls back to the resolved `annotationDefaults` theme (test, then spec, then config), then to the built-in theme. | — | | position | one of: - string - object([Annotation point](/reference/schemas/annotation-point)) - object([Annotation offset](/reference/schemas/annotation-offset)) | Optional. Where to place the annotation relative to its target. Accepts a named region, an absolute point, or an offset that nudges the default placement. | — | | track | boolean | Optional. If `true`, the annotation follows its element as the page scrolls or reflows. Applies to recordings; inert in still screenshots, which capture a single moment. | — | | transition | object([Annotation transition](/reference/schemas/annotation-transition)) | Optional. How the annotation enters and leaves. Applies to recordings; inert in still screenshots, which render the settled state. | — | | duration | number | Optional. Milliseconds to display the annotation before it clears itself. Omit to display it until an `annotate` step clears it. Applies to recordings; inert in still screenshots. Minimum: 0 | — | | all | boolean | Optional. If `true`, annotates every element matching the target instead of only the first. Most useful with `blur`, where redacting only the first match can leave sensitive content visible. | — | ## Examples ```json { "outline": "#submit-button" } ``` ```json { "badge": "#expiry", "label": "2" } ``` ```json { "callout": { "elementTestId": "cvv-input" }, "label": "Never stored — sent straight to the payment processor", "position": "right", "style": { "maxWidth": 240, "fontSize": 13 } } ``` ```json { "arrow": { "elementAttribute": { "data-state": "invalid" } }, "position": "bottom-left" } ``` ```json { "text": { "position": "top-right" }, "label": "Demo environment — sample data", "style": { "background": "#0F172A", "color": "#FDE047", "padding": 8, "opacity": 0.9 } } ``` ```json { "id": "redact-api-keys", "blur": { "elementAttribute": { "data-sensitive": true } }, "all": true, "track": true, "style": { "intensity": 22 }, "transition": { "enter": "none" } } ``` ```json { "callout": { "elementTestId": "dashboard-loaded", "timeout": 15000 }, "label": "Your dashboard, once the first sync finishes" } ``` ```json { "id": "usage-highlight", "outline": { "elementClass": [ "form-field", "/^billing-/" ] }, "duration": 3500, "transition": { "enter": "draw", "exit": "fade", "durationMs": 400 } } ```