Skip to main content
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.
​
type
'sticker'
required
Annotation type identifier.
​
sticker
string
required
The sticker to display. Available options: 'rocket', 'clapping-hands', 'thumbs-up', 'thumbs-down', 'grinning-face'.
​
rowIndex
number
Zero-based index of the row this annotation targets.
​
columnKey
string
Key of the column this annotation targets.
​
rowValue
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'
    }
  ]
};

​
Tooltip

Displays a custom tooltip with rich text content at a specific data point.
​
type
'tooltip'
required
Annotation type identifier.
​
caption
JSONContent
required
Rich text (TipTap JSON) shown inside the tooltip.
​
rowIndex
number
Zero-based index of the row this annotation targets.
​
columnKey
string
Key of the column this annotation targets.
​
rowValue
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.
​
type
'highlight'
required
Annotation type identifier.
​
highlight
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
​
rowIndex
number
Zero-based index of the row this annotation targets.
​
columnKey
string
Key of the column this annotation targets.
​
rowValue
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.
​
type
'text'
required
Annotation type identifier.
​
content
JSONContent
required
Rich text content (TipTap JSON).
​
x
number
required
Horizontal position relative to the plot area (0 to 1). Represents the midpoint of the text box.
​
y
number
required
Vertical position relative to the plot area (0 to 1). Represents the midpoint of the text box.
​
width
number
required
Width relative to the plot area (0 to 1).
​
backgroundColor
string
Background color for the text box (hex color).
​
backgroundColorStyle
'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.
​
type
'arrow'
required
Annotation type identifier.
​
startX
number
required
Starting horizontal position relative to the plot area (0 to 1).
​
startY
number
required
Starting vertical position relative to the plot area (0 to 1).
​
endX
number
required
Ending horizontal position relative to the plot area (0 to 1).
​
endY
number
required
Ending vertical position relative to the plot area (0 to 1).
​
color
string | null
required
Arrow color (hex color or null for default).
​
thickness
'thin' | 'medium' | 'thick'
required
Arrow line thickness.
​
startArrowheadStyle
'none' | 'line-arrow'
required
Arrowhead style at the start of the line.
​
lineStyle
'solid' | 'dashed'
required
Line style.
​
endArrowheadStyle
'none' | 'line-arrow'
required
Arrowhead style at the end of the line.
​
hasStickerStyle
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.
​
type
'difference-arrow'
required
Annotation type identifier.
​
show
string
required
What to display:
  • 'absolute-difference' - Show the numeric difference
  • 'relative-difference' - Show the percentage change
  • 'proportion' - Show the ratio between values
​
start
object
required
Starting data point for the difference calculation.
​
end
object
required
Ending data point for the difference calculation. Same structure as start.
​
color
string | null
required
Arrow color (hex color or null for default).
​
size
'small' | 'medium' | 'large'
required
Arrow size.
​
labelPosition
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.
​
type
'shape'
required
Annotation type identifier.
​
shape
'rectangle'
required
Shape type. Currently only rectangles are supported.
​
layer
'belowPlot' | 'abovePlot'
required
Whether to render the shape below or above the plot area.
​
x
number
required
Horizontal position relative to the plot area (0 to 1).
​
y
number
required
Vertical position relative to the plot area (0 to 1).
​
width
number
required
Width relative to the plot area (0 to 1).
​
height
number
required
Height relative to the plot area (0 to 1).
​
fillColor
string
required
Fill color for the shape (hex color).
​
fillOpacity
number
required
Fill opacity (0 to 1).
​
strokeWidth
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:
PropertyTypeDescription
idstringA unique identifier for the color
labelstring (optional)A human-readable name for the color
valuestringThe hex color value
import { graphyThemeLight } from '@graphysdk/core';

const customTheme = {
  ...graphyThemeLight,
  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:
  1. 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.
  2. 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 { graphyThemeLight } from '@graphysdk/core';

const customTheme = {
  ...graphyThemeLight,
  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.