# Callouts and masks

A callout draws on one mark. shotlist computes the position, extends the canvas when a label or a disc needs room outside the captured region, and moves a label that would overlap one already drawn.

screenshots/recipes/order-row.yaml

```
marks:
  amount: { within: clip, text: $42.00 }
  status: { within: clip, text: Open }

callouts:
  - { mark: amount, text: What they owe, place: left }
  - mark: status
    text:
      - Where it stands
      - and who is waiting
    place: bottom
    dy: 12
```

## Callout fields

| Field | Default | Effect |
| --- | --- | --- |
| `mark` | required | Which mark to draw on |
| `text` | — | Label text: one string, or a list with one line each |
| `n` | — | Number shown in a disc |
| `place` | `auto` | `auto`, `left`, `right`, `top`, `bottom`, or `corner` |
| `badge` | `tl` | Anchor for `place: corner`: `tl tc tr ml mr bl br bc` |
| `box` | `true` | Whether to draw the outline |
| `inside` | see below | Whether the label or disc sits over the capture |
| `dx` | `0` | Nudge across, in image pixels |
| `dy` | `0` | Nudge down, in image pixels |
| `pad` | [`style.box.pad`](/docs/reference/configuration/#style) | Distance between the outline and the element |
| `gap` | [`style.label.gap`](/docs/reference/configuration/#style) | Distance between the label and the outline |

Left unset, a disc (`place: corner`) sits inside, on the box, and a label on a named side sits outside, in a margin the canvas grows to make. An explicit `place` or `inside` is obeyed exactly. For what `auto` weighs, see [How labels are placed](/docs/explanation/placement/).

## numbered

A list is shorthand for one numbered disc per mark, in the order given:

screenshots/recipes/statblock.yaml

```
marks:
  header: { css: '.statblock-header' }
  abilities: { css: '.abilities' }
  defenses: { css: '.defenses' }

numbered: [header, abilities, defenses]
```

A mapping carries that list under `marks`, and applies every other key to all of them:

screenshots/recipes/statblock.yaml

```
marks:
  header: { css: '.statblock-header' }
  abilities: { css: '.abilities' }
  defenses: { css: '.defenses' }

numbered:
  marks: [header, abilities, defenses]
  box: false
  badge: ml
  inside: false
```

| Key | Default | Effect |
| --- | --- | --- |
| `marks` | required | Marks to number, in order |
| `box` | `true` | Whether to outline each mark |
| `badge` | `tl` | Which corner or edge the disc anchors to |
| `inside` | `true` | Whether discs sit over the capture |
| `dx`, `dy` | `0` | Nudge, in image pixels |
| `pad` | [`style.box.pad`](/docs/reference/configuration/#style) | Distance between the outline and the element |

`place` is not among them. A numbered disc is always `corner`, and `badge` chooses which one.

## mask

A list of [queries](/docs/reference/queries/). Each matched region is painted with `style.mask.fill` before the callouts are drawn, so a callout may still point at a masked region.

screenshots/recipes/dashboard.yaml

```
mask:
  - { within: clip, css: '.updated-at' }
  - { rect: [172, 84, 52, 20] }
```

A mask covers every element its query matches. Add `pick` or `nth` to select one. A mask that matches nothing stops the run. With `source: file`, masks are literal rectangles.

Masking changes the image. To leave a region in the image but out of the `--check` comparison, use [`check.ignore`](/docs/reference/recipe/#check) instead.

Written by Nicola Mustone · Applies to shotlist 0.6.0 · Maintained by Nicola Mustone

Published date unavailable · Updated date unavailable · [View source](https://github.com/SirDarcanos/shotlist.dev/blob/main/src/pages/docs/reference/callouts.astro) · [Propose a correction](https://github.com/SirDarcanos/shotlist.dev/edit/main/src/pages/docs/reference/callouts.astro)