> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField path="type" type="'sticker'" required>
  Annotation type identifier.
</ParamField>

<ParamField path="sticker" type="string" required>
  The sticker to display. Available options: `'rocket'`, `'clapping-hands'`, `'thumbs-up'`, `'thumbs-down'`,
  `'grinning-face'`.
</ParamField>

<ParamField path="rowIndex" type="number" optional>
  Zero-based index of the row this annotation targets.
</ParamField>

<ParamField path="columnKey" type="string" optional>
  Key of the column this annotation targets.
</ParamField>

<ParamField path="rowValue" type="string | number | null" optional>
  Optional categorical value to pin the annotation to. Used to remap the annotation if the dataset changes.
</ParamField>

```tsx theme={null}
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.

<ParamField path="type" type="'tooltip'" required>
  Annotation type identifier.
</ParamField>

<ParamField path="caption" type="JSONContent" required>
  Rich text (TipTap JSON) shown inside the tooltip.
</ParamField>

<ParamField path="rowIndex" type="number" optional>
  Zero-based index of the row this annotation targets.
</ParamField>

<ParamField path="columnKey" type="string" optional>
  Key of the column this annotation targets.
</ParamField>

<ParamField path="rowValue" type="string | number | null" optional>
  Optional categorical value to pin the annotation to.
</ParamField>

```tsx theme={null}
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.

<ParamField path="type" type="'highlight'" required>
  Annotation type identifier.
</ParamField>

<ParamField path="highlight" type="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
</ParamField>

<ParamField path="rowIndex" type="number" optional>
  Zero-based index of the row this annotation targets.
</ParamField>

<ParamField path="columnKey" type="string" optional>
  Key of the column this annotation targets.
</ParamField>

<ParamField path="rowValue" type="string | number | null" optional>
  Optional categorical value to pin the annotation to.
</ParamField>

```tsx theme={null}
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.

<ParamField path="type" type="'text'" required>
  Annotation type identifier.
</ParamField>

<ParamField path="content" type="JSONContent" required>
  Rich text content (TipTap JSON).
</ParamField>

<ParamField path="x" type="number" required>
  Horizontal position relative to the plot area (0 to 1). Represents the midpoint of the text box.
</ParamField>

<ParamField path="y" type="number" required>
  Vertical position relative to the plot area (0 to 1). Represents the midpoint of the text box.
</ParamField>

<ParamField path="width" type="number" required>
  Width relative to the plot area (0 to 1).
</ParamField>

<ParamField path="backgroundColor" type="string" optional>
  Background color for the text box (hex color).
</ParamField>

<ParamField path="backgroundColorStyle" type="'fade' | 'opaque'" optional>
  Background style: `'fade'` for semi-transparent or `'opaque'` for solid.
</ParamField>

```tsx theme={null}
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.

<ParamField path="type" type="'arrow'" required>
  Annotation type identifier.
</ParamField>

<ParamField path="startX" type="number" required>
  Starting horizontal position relative to the plot area (0 to 1).
</ParamField>

<ParamField path="startY" type="number" required>
  Starting vertical position relative to the plot area (0 to 1).
</ParamField>

<ParamField path="endX" type="number" required>
  Ending horizontal position relative to the plot area (0 to 1).
</ParamField>

<ParamField path="endY" type="number" required>
  Ending vertical position relative to the plot area (0 to 1).
</ParamField>

<ParamField path="color" type="string | null" required>
  Arrow color (hex color or null for default).
</ParamField>

<ParamField path="thickness" type="'thin' | 'medium' | 'thick'" required>
  Arrow line thickness.
</ParamField>

<ParamField path="startArrowheadStyle" type="'none' | 'line-arrow'" required>
  Arrowhead style at the start of the line.
</ParamField>

<ParamField path="lineStyle" type="'solid' | 'dashed'" required>
  Line style.
</ParamField>

<ParamField path="endArrowheadStyle" type="'none' | 'line-arrow'" required>
  Arrowhead style at the end of the line.
</ParamField>

<ParamField path="hasStickerStyle" type="boolean" required>
  Whether to use a sticker outline style for the arrow.
</ParamField>

```tsx theme={null}
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.

<ParamField path="type" type="'difference-arrow'" required>
  Annotation type identifier.
</ParamField>

<ParamField path="show" type="string" required>
  What to display: - `'absolute-difference'` - Show the numeric difference - `'relative-difference'` - Show the
  percentage change - `'proportion'` - Show the ratio between values
</ParamField>

<ParamField path="start" type="object" required>
  Starting data point for the difference calculation.

  <Expandable title="properties">
    <ParamField path="rowIndex" type="number" optional>
      Zero-based row index.
    </ParamField>

    <ParamField path="columnKey" type="string" optional>
      Column key.
    </ParamField>

    <ParamField path="rowValue" type="string | number | null" optional>
      Optional categorical value.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="end" type="object" required>
  Ending data point for the difference calculation. Same structure as `start`.
</ParamField>

<ParamField path="color" type="string | null" required>
  Arrow color (hex color or null for default).
</ParamField>

<ParamField path="size" type="'small' | 'medium' | 'large'" required>
  Arrow size.
</ParamField>

<ParamField path="labelPosition" type="number" optional>
  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
</ParamField>

```tsx theme={null}
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.

<ParamField path="type" type="'shape'" required>
  Annotation type identifier.
</ParamField>

<ParamField path="shape" type="'rectangle'" required>
  Shape type. Currently only rectangles are supported.
</ParamField>

<ParamField path="layer" type="'belowPlot' | 'abovePlot'" required>
  Whether to render the shape below or above the plot area.
</ParamField>

<ParamField path="x" type="number" required>
  Horizontal position relative to the plot area (0 to 1).
</ParamField>

<ParamField path="y" type="number" required>
  Vertical position relative to the plot area (0 to 1).
</ParamField>

<ParamField path="width" type="number" required>
  Width relative to the plot area (0 to 1).
</ParamField>

<ParamField path="height" type="number" required>
  Height relative to the plot area (0 to 1).
</ParamField>

<ParamField path="fillColor" type="string" required>
  Fill color for the shape (hex color).
</ParamField>

<ParamField path="fillOpacity" type="number" required>
  Fill opacity (0 to 1).
</ParamField>

<ParamField path="strokeWidth" type="number" required>
  Border stroke width in pixels.
</ParamField>

```tsx theme={null}
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                 |

```tsx theme={null}
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:

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`](/sdk/reference/graph-theme#graphthemeannotationcolorids) for the available properties.

```tsx theme={null}
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.