Docs

Appearance

Return to top
On this page

Annotate Image

When putting together a support article that includes images, annotating those images with text, shapes, arrows etc. to call out specific parts of the image is a common use case that allows you can speak to specific parts of a bigger context.

Types of Image Annotation

We currently support the following types of annotation:

  • Rectangle
  • Arrow
  • Enumeration
  • Text

The bare minimum required to annotate screenshot

POST /screenshot

You can annotate a screenshot by specifying the selector(s) in the annotate property. For example:

json
{
  "url": "https://demo.baremetrics.com/stats/mrr",
  "elementSelector": [
    "section.main-graph.mrr"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "orange",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "type": "rectangle",
      "selectors": [
        "#s2id_autogen5"
      ]
    }
  ]
}

List of supported attributes

You can customize each annotation type by either specifying a list of attributes for all annotations as a global configuration or by applying a specific setting to each annotation.

OptionDefault valueAnnotation typeDescription
offset10AllAdd space around the element (think CSS padding) e.g 10
color#dc2626AllThe border color of the rectangle e.g green, #800080
width4rectangle, arrow, enumerationThe border width of the rectangle e.g 4
positionbottomtextText placement. Possible values: bottom, top
size20textThe size in px of the text
message''textThe message to be displayed.

Usage

Below is a series of examples demonstrating various properties of the screenshot API endpoint focusing on the annotate property.

Example 1: Adding multiple rectangle annotations

json
{
  "url": "https://demo.baremetrics.com/stats/mrr",
  "elementSelector": [
    "section.main-graph.mrr"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "purple",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "type": "rectangle",
      "selectors": [
        "#s2id_autogen5"
      ]
    },
    {
      "type": "rectangle",
      "selectors": [
        "#s2id_autogen3"
      ]
    }
  ]
}

Example 2: Specifying multiple selectors type per annotation

json
{
  "url": "https://demo.baremetrics.com/stats/mrr",
  "elementSelector": [
    "section.main-graph.mrr"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "red",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "type": "rectangle",
      "selectors": [
        "#s2id_autogen5.fake",
        "xpath///*[@id='s2id_autogen5']"
      ]
    },
    {
      "type": "rectangle",
      "selectors": [
        "#s2id_autogen3.fake",
        "xpath///*[@id='s2id_autogen3']"
      ]
    },
    {
      "type": "rectangle",
      "selectors": [
        "body > div.container > div.container--inner > section > main > section > div.metric-stat > div.col.col-main > h1.fake",
        "xpath//html/body/div[1]/div[2]/section/main/section/div[2]/div[1]/h1"
      ]
    }
  ]
}

Example 3: Global annotation configuration

json
{
  "global": {
    "annotation": {
      "color": "purple",
      "width": 3,
      "offset": 3
    }
  },
  "url": "https://example.org/",
  "elementSelector": [
    "body > div"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "brown",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "type": "rectangle",
      "selectors": [
        "body > div > p:nth-child(2)"
      ]
    }
  ]
}

Example 4: Overriding the default offset, width and color properties.

json
{
  "url": "https://example.org/",
  "elementSelector": [
    "body > div"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "brown",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "offset": 10,
      "width": 5,
      "color": "orange",
      "type": "rectangle",
      "selectors": [
        "body > div > p:nth-child(2)"
      ]
    }
  ]
}

Example 5: Adding various annotation types to the same screenshot

json
{
  "url": "https://example.org/",
  "elementSelector": [
    "body > div"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "brown",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "offset": 10,
      "width": 5,
      "color": "orange",
      "type": "rectangle",
      "selectors": [
        "body > div > p:nth-child(2)"
      ]
    },
    {
      "offset": 10,
      "width": 5,
      "color": "purple",
      "type": "arrow",
      "selectors": [
        "body > div > p:nth-child(2)"
      ]
    },
    {
      "offset": 20,
      "width": 1,
      "color": "pink",
      "type": "enumeration",
      "selectors": [
        "body > div > p:nth-child(2)"
      ]
    }
  ]
}

Example 6: Adding a text annotation

json
{
  "url": "https://example.org/",
  "elementSelector": [
    "body > div"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "brown",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "type": "text",
      "message": "Hello World",
      "position": "bottom",
      "size": 12,
      "offset": 12,
      "color": "white",
      "selectors": [
        "body > div > p:nth-child(2)"
      ]
    }
  ]
}