Annotations

Annotations allow users to add visual elements like arrows, shapes and text to graphs to highlight important data points or provide additional context.

Annotation types

Graphy supports seven types of annotations.

Sticker

Adds an emoji sticker to a specific data point on the chart.

'sticker'

required

Annotation type identifier.

string

required

The sticker to display. Available options: 'rocket', 'clapping-hands', 'thumbs-up', 'thumbs-down', 'grinning-face'.

number

Zero-based index of the row this annotation targets.

string

Key of the column this annotation targets.

string | number | null

Optional categorical value to pin the annotation to. Used to remap the annotation if the dataset changes.

const config: GraphConfig = {
  annotations: [
    {
      id: 'sticker-1',
      type: 'sticker',
      sticker: 'rocket',
      rowIndex: 2,
      columnKey: 'sales',
    },
  ],
};

Displays a custom tooltip with rich text content at a specific data point.

'tooltip'

required

Annotation type identifier.

JSONContent

required

Rich text (TipTap JSON) shown inside the tooltip.

number

Zero-based index of the row this annotation targets.

string

Key of the column this annotation targets.

string | number | null

Optional categorical value to pin the annotation to.

const config: GraphConfig = {
  annotations: [
    {
      id: 'tooltip-1',
      type: 'tooltip',
      caption: {
        type: 'doc',
        content: [
          {
            type: 'paragraph',
            content: [{ type: 'text', text: 'Peak sales period' }],
          },
        ],
      },
      rowIndex: 5,
      columnKey: 'revenue',
    },
  ],
};

Highlight

Highlights a data point, entire series or all data points at a specific x-value.

'highlight'

required

Annotation type identifier.

string

required

What to highlight: - 'data-point' - Highlight a single data point - 'series' - Highlight an entire series - 'x-value' - Highlight all data points at a specific x-value

number

Zero-based index of the row this annotation targets.

string

Key of the column this annotation targets.

string | number | null

Optional categorical value to pin the annotation to.

const config: GraphConfig = {
  annotations: [
    {
      id: 'highlight-1',
      type: 'highlight',
      highlight: 'x-value',
      rowIndex: 3,
    },
  ],
};

Text

Adds a text box with rich text content positioned relative to the plot area.

'text'

required

Annotation type identifier.

JSONContent

required

Rich text content (TipTap JSON).

number

required

Horizontal position relative to the plot area (0 to 1). Represents the midpoint of the text box.

number

required

Vertical position relative to the plot area (0 to 1). Represents the midpoint of the text box.

number

required

Width relative to the plot area (0 to 1).

string

Background color for the text box (hex color).

'fade' | 'opaque'

Background style: 'fade' for semi-transparent or 'opaque' for solid.

const config: GraphConfig = {
  annotations: [
    {
      id: 'text-1',
      type: 'text',
      content: {
        type: 'doc',
        content: [
          {
            type: 'paragraph',
            content: [{ type: 'text', text: 'Notable trend' }],
          },
        ],
      },
      x: 0.5,
      y: 0.3,
      width: 0.2,
      backgroundColor: '#ffffff',
      backgroundColorStyle: 'opaque',
    },
  ],
};

Arrow

Draws an arrow between two points on the chart with customizable styling.

'arrow'

required

Annotation type identifier.

number

required

Starting horizontal position relative to the plot area (0 to 1).

number

required

Starting vertical position relative to the plot area (0 to 1).

number

required

Ending horizontal position relative to the plot area (0 to 1).

number

required

Ending vertical position relative to the plot area (0 to 1).

string | null

required

Arrow color (hex color or null for default).

'thin' | 'medium' | 'thick'

required

Arrow line thickness.

'none' | 'line-arrow'

required

Arrowhead style at the start of the line.

'solid' | 'dashed'

required

Line style.

'none' | 'line-arrow'

required

Arrowhead style at the end of the line.

boolean

required

Whether to use a sticker outline style for the arrow.

const config: GraphConfig = {
  annotations: [
    {
      id: 'arrow-1',
      type: 'arrow',
      startX: 0.2,
      startY: 0.8,
      endX: 0.6,
      endY: 0.3,
      color: '#ef4444',
      thickness: 'medium',
      startArrowheadStyle: 'none',
      lineStyle: 'solid',
      endArrowheadStyle: 'line-arrow',
      hasStickerStyle: false,
    },
  ],
};

Difference arrow

Shows the difference between two data points with an automatic label displaying the calculated difference.

'difference-arrow'

required

Annotation type identifier.

string

required

What to display: - 'absolute-difference' - Show the numeric difference - 'relative-difference' - Show the percentage change - 'proportion' - Show the ratio between values

object

required

Starting data point for the difference calculation.

Show properties

number

Zero-based row index.

string

Column key.

string | number | null

Optional categorical value.

object

required

Ending data point for the difference calculation. Same structure as start.

string | null

required

Arrow color (hex color or null for default).

'small' | 'medium' | 'large'

required

Arrow size.

number

Position of the label along the arrow (0 to 1): - 0 - Label at the start (default) - 0.5 - Label in the middle - 1 - Label at the end

const config: GraphConfig = {
  annotations: [
    {
      id: 'diff-1',
      type: 'difference-arrow',
      show: 'relative-difference',
      start: {
        rowIndex: 0,
        columnKey: 'sales',
      },
      end: {
        rowIndex: 5,
        columnKey: 'sales',
      },
      color: '#10b981',
      size: 'medium',
      labelPosition: 0.5,
    },
  ],
};

Shape

Adds a rectangular shape to the chart, either below or above the plot area.

'shape'

required

Annotation type identifier.

'rectangle'

required

Shape type. Currently only rectangles are supported.

'belowPlot' | 'abovePlot'

required

Whether to render the shape below or above the plot area.

number

required

Horizontal position relative to the plot area (0 to 1).

number

required

Vertical position relative to the plot area (0 to 1).

number

required

Width relative to the plot area (0 to 1).

number

required

Height relative to the plot area (0 to 1).

string

required

Fill color for the shape (hex color).

number

required

Fill opacity (0 to 1).

number

required

Border stroke width in pixels.

const config: GraphConfig = {
  annotations: [
    {
      id: 'shape-1',
      type: 'shape',
      shape: 'rectangle',
      layer: 'belowPlot',
      x: 0.1,
      y: 0.2,
      width: 0.3,
      height: 0.4,
      fillColor: '#fef3c7',
      fillOpacity: 0.5,
      strokeWidth: 2,
    },
  ],
};

Canvas colors

Canvas colors are the default options displayed in the color picker for annotations that allow the user to customize strokes, fills and text colors. Each canvas color is defined as an object with the following properties:

Property	Type	Description
`id`	`string`	A unique identifier for the color
`label`	`string` (optional)	A human-readable name for the color
`value`	`string`	The hex color value

import { graphyLightTheme } from '@graphysdk/core';

const customTheme = {
  ...graphyLightTheme,
  canvasColors: [
    { id: 'default', label: 'Black', value: '#000000' },
    { id: 'blue', label: 'Blue', value: '#3b82f6' },
    { id: 'green', label: 'Green', value: '#10b981' },
    { id: 'red', label: 'Red', value: '#ef4444' },
  ],
};

Color persistence across themes

The id property is important for maintaining color consistency when switching between themes. When a user applies a canvas color to an annotation (such as text color or arrow stroke), the color’s id is stored rather than the hex value itself. When the theme changes:

Matching ID found: If the new theme contains a canvas color with the same id, the annotation automatically uses the color value from the new theme. This allows colors to adapt appropriately—for example, a “default” color might be black in a light theme but white in a dark theme.
No matching ID: If the new theme does not contain a canvas color with the same id, the annotation falls back to the first canvas color in the new theme’s canvasColors array.

This behavior ensures that annotations remain visible and appropriately styled regardless of theme changes, while giving you control over how colors translate between your light and dark themes.

Default annotation colors

When users create new annotations, Graphy applies default colors automatically. You can configure these defaults via the defaultAnnotationColorIds property in your theme, which references the id values from your canvasColors array. See GraphThemeAnnotationColorIds for the available properties.

import { graphyLightTheme } from '@graphysdk/core';

const customTheme = {
  ...graphyLightTheme,
  canvasColors: [
    { id: 'default', label: 'Black', value: '#000000' },
    { id: 'blue', label: 'Blue', value: '#3b82f6' },
    { id: 'accent', label: 'Accent', value: '#ef4444' },
  ],
  defaultAnnotationColorIds: {
    arrowStroke: 'accent',
    shapeFill: 'blue',
  },
};

Fallback behavior

If a default annotation color is not configured or references an invalid id, Graphy automatically falls back to the first canvas color in the canvasColors array. This ensures annotations always render with a valid color, even if the configuration is incomplete.

Get Started

Graph types

Customisation

Configuration

Editor

Advanced

Reference

Annotation types

Sticker

Tooltip

Highlight

Text

Arrow

Difference arrow

Shape

Canvas colors

Color persistence across themes

Default annotation colors

Fallback behavior

​Annotation types

​Sticker

​Tooltip

​Highlight

​Text

​Arrow

​Difference arrow

​Shape

​Canvas colors

​Color persistence across themes

​Default annotation colors

​Fallback behavior

Annotation types

Sticker

Tooltip

Highlight

Text

Arrow

Difference arrow

Shape

Canvas colors

Color persistence across themes

Default annotation colors

Fallback behavior