Annotations

Annotations help explain narratives in your charts and allow users to provide context and highlight important insights directly in the chart.

Annotations do not scale during zooming and stay readable at any chart size and zoom level. You can style and customize them to fit any application design, and export annotated charts using the export method.

To learn more, head over to the Annotation stories and the Annotations API Reference.

Annotations

Log in to view live examples

Creating

In the chart, you can annotate nodes, links and open and closed combos. You can also create free-standing annotations without any subjects.

Annotations can have a single or multiple subjects, and even annotate a combination of nodes, links and combos.

Annotations are passed in the items prop. The subject array is set differently for annotations with and without subjects:

<Chart
  items={{
    node1: { color: '#17BA99' },
    annotation1: {
      subject: 'node1',    //  node1 is the subject
      label: { text: 'Node annotation' },
    },
    annotation2: {
      subject: [],    //  an empty array indicates no subjects
      label: { text: 'Annotation without subjects' },
    },
  }}
  annotationPositions={{
    annotation2: { x: 0, y: -200 },   // required for no-subject annotations
  }}
/>

Annotations without subjects still require the subject array to be set. You can set it to an empty array.

Note that if your application code contains logic checking whether a chart item is either a node or a link ( if (!item.id1) { code for nodes }), adding annotations into your code may require changes to also consider annotations.

See how to annotate items in the Annotations Basics story.

Positioning

Annotations are drawn in their own separate layer on top of the chart. There are two ways of positioning annotations:

Subject-relative positioning

You can position annotations relative to their subjects and control their angle and the distance from their subjects in the annotationPositions prop.

When a layout is run or when their subjects are repositioned, annotations also move to keep their position relative to their subjects. Manually dragging the annotation updates its position.

Subject-relative annotations are drawn when at least one of their subjects is visible in the chart. If subjects are inside a combo, annotations are only drawn when the combo is open.

You can use the getRelativeAnnotationPosition instance method to get subject-relative positions of annotations.

World-coordinate positioning

You can position any annotation (with or without subjects) on the chart in world coordinates by setting the x and y properties in the annotationPositions prop.

When positioned using coordinates, annotations remain fixed even during changes to the chart such as zooming, panning, items moving or subject changing. Manually dragging the annotation updates its position.

World-coordinate annotations do not depend on subjects for positioning and are drawn even if no subjects are visible in the chart.

You can use the getWorldAnnotationPosition instance method to get world-coordinate positions of annotations.

Styling

A default annotation has two main parts:

A body with text or other content, styled in the annotation object A connector linking the annotation to subjects, styled in the connectorStyle object The connector further splits into three parts: A line or lines pointing to the subject(s) An optional dot or arrow subjectEnd decoration An optional circular or rectangular container around node or combo subjects

The connector is styled in the connectorStyle object. The color, lineStyle and width options style the whole connector. Setting width to 0 hides the connector and creates an annotation that isn't visibly connected to subjects but stays in a relative position to them.

See the Annotations Basics story to learn more about different annotation parts.

The body is styled in the annotation object. The shape and border objects and the color property customize the dimensions, border style and background of the body shape. The glyph and label arrays can be used to add multiple labels and glyphs on the body.

Take a look at the Advanced Annotation Gallery for various examples and levels of styling.

Custom User Controls

Using labels or glyphs, you can create custom user controls on annotations and respond to chart events triggered by interacting with the controls:

// example onClick handler where the 2nd label is a delete button

const clickHandler = ({ id, itemType, subItem }) => {
  const item = items[id];
  if (
    item &&
    itemType === 'annotation' &&        // if this item is an annotation
    subItem.type === 'label' &&         // and the clicked label
    subItem.index === 1                 // has an index of 1 in the label array
  ) {
    // code for delete button here
  }
};

Find examples of user controls in the Advanced Annotation Gallery story.

You can also create annotations with user-editable text fields or any other custom elements by overlaying your own HTML elements over ReGraph annotations. For more details, head to the User-created Annotations story.

Filtering

Subject-relative annotations are drawn when at least one of their subjects is visible in the chart.

World-coordinate annotations are drawn even if no subjects are visible in the chart.

This means that annotations without subjects are always visible as as they can only be positioned using world coordinates.

Special Behavior

While annotations are loaded into the chart just like nodes and links, they are a special type of always-readable chart item that are not considered as items by the layout algorithms. As a result, some of their behavior is different from other chart items:

• Annotations cannot be selected.
• Annotations cannot be foregrounded or faded.
• Annotations cannot be shown on a Leaflet map.