Skip to main content


The Annotations component allows you to add informative text to your visualizations. It is compatible with both XY and Single containers.

Basic Configuration

Include the Annotations component in your Single or XY container with an array of items. A basic example looks like:

<VisXYContainer yDomain={[0,15]} data={data}>
<VisArea x={x} y={y} curveType="linear"/>
<VisAnnotations items={items}/>

where items has the following definition:

let items: AnnotationItem[] = [
{ x: 12, y: 10, content: { text: 'Chart Title', fontSize: 30 }},
{ x: 15, y: 50, width: 200, content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam rutrum dignissim lorem, a mollis lacus lacinia eget' },
{ x: '50%', y: '20%', content: 'Label #1', subject: { x: '42%', y: '38%' }},
{ x: '70%', y: '40%', content: 'Label #2', subject: { x: '86%', y: '50%' }},


The items property accepts an array of AnnotationItem objects. For minimum configuration, include content (the text) and an optional subject (the highlighted area).

AnnotationItem Type

type AnnotationItem = {
// Base properties
content: string | UnovisText | UnovisText[];
subject?: AnnotationSubject;

// Position and size properties
x?: number | `${number}%` | `${number}px`
y?: number | `${number}%` | `${number}px`
width?: number | `${number}%` | `${number}px`
height?: number | `${number}%` | `${number}px`

// Wrapping and alignment properties
separator?: string | string[];
verticalAlign?: VerticalAlign | string;
textAlign?: TextAlign | string;
wordBreak?: boolean;
fastMode?: boolean;

// Miscellaneous
cursor: string;

Text Content

The content property accepts a string, a UnovisText object, or an array of UnovisText objects.

As a basic example, you can use a string:

let items: AnnotationItem[] = [
{ content: 'Item 1' }

When we place Annotations in an empty chart with the above items array, we get the default text appearance:


Styled Text

To customize font or color of your text, provide content with an object of type UnovisText. In this case, you put the desired string content to the text property, and additional properties can be set.

items = [{
content: { text: 'Item 2', color: 'red' }

Multi-Line Text

You can group a single annotation into multiple lines of text by providing an array of UnovisText items to the content property.

The following is also a valid input for items:

items = [{
content: [
text: 'Item 3',
fontSize: 24,
fontWeight: 600
text: 'contains multiple text blocks lines',
fontFamily: 'cursive',
fontSize: 16
text: 'with custom styles',
color: 'green',
fontWeight: 'bold'

UnovisText type

type UnovisText = {
// The text content to be displayed.
text: string;
// The font size of the text in pixels.
fontSize: number;
// The font family of the text.
fontFamily?: string;
// The font weight of the text.
fontWeight?: number;
// The color of the text.
color?: string;
// The line height scaling factor for the text.
lineHeight?: number;
// The top margin of the text block in pixels
marginTop?: number;
// The bottom margin of the text block in pixels
marginBottom?: number;
// The font width-to-height ratio
fontWidthToHeightRatio?: number;


The x and y properties define the position of the annotation. They can be specified in pixels (number or string) or as a percentage of the container size. You can also add textAlign and verticalAlign properties to adjust the alignment of the text.

For example, the following is a valid definition of

const items= [
content: 'Item A',
x: 0,
y: 10,
subject: { x: 50, y: 50 }
content: 'Item B',
x: '150px',
y: '20px',
textAlign: 'right',
subject: { x: '100px', y: '60px' }
content: 'Item C',
x: '50%',
y: '100%',
textAlign: 'center',
verticalAlign: 'bottom',
subject: { x: '50%', y: '70%' },


Subjects are focal points of the annotation. They can be used to highlight a specific area or point. The minimum configuration of a subject is an x and y coordinate.

items = [{
content: 'Item with Subject',
subject: { x: '50%', y: 20 }

Subject Points

The point corresponds to the center of the subject area. When a radius is provided, the point becomes visible.

items = [{
content: 'Item with Subject',
subject: { x: '50%', y: 2, radius: 4 }

AnnotationSubject Type

export type AnnotationSubject = {
x: LengthUnit | (() => LengthUnit);
y: LengthUnit | (() => LengthUnit);
/** Subject radius */
radius?: number;
/** Subject fill color */
fillColor?: string;
/** Subject stroke color */
strokeColor?: string;
/** Subject stroke-dasharray configuration */
strokeDasharray?: string;
/** Padding between the subject and the connector line */
padding?: number;
/** Connector line color */
connectorLineColor?: string;
/** Connector line stroke-dasharray configuration */
connectorLineStrokeDasharray?: string;

CSS Variables

--vis-annotations-connector-stroke-color: #444;
--vis-annotations-connector-stroke-width: 1px;
--vis-annotations-connector-stroke-dasharray: none;

--vis-annotations-subject-stroke-color: #444;
--vis-annotations-subject-fill-color: none;
--vis-annotations-subject-stroke-dasharray: none;

--vis-dark-annotations-conntector-stroke-color: #fff;
--vis-dark-annotations-subject-stroke-color: #fff;

Component Props

* required property