React Chart - annotations
Annotations are images and text blocks that provide additional information on the visualized data. The image below demonstrates their appearance:
To configure annotations, assign an array of objects to the annotations[] option. Each object should have the type field set to "text" or "image". Depending on the type, specify the annotation's text or image option:
jQuery
$(function() { $("chartContainer").dxChart({ annotations: [{ type: "text", text: "Annotation text" }, { type: "image", image: "http://image/url/myimage.png" }] }); });
Angular
<dx-chart ... > <dxi-annotation type="text" text="Annotation text"> </dxi-annotation> <dxi-annotation type="image" image="http://image/url/myimage.png"> </dxi-annotation> </dx-chart>
import { Component } from '@angular/core'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { // ... }
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxChartModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxChartModule ], providers: [ ], bootstrap: [AppComponent] }) export class AppModule { }
Vue
<template> <DxChart ... > <DxAnnotation type="text" text="Annotation text" /> <DxAnnotation type="image" image="http://image/url/myimage.png" /> </DxChart> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DxChart, { DxAnnotation } from 'devextreme-vue/chart'; export default { components: { DxChart, DxAnnotation }, data() { // ... } } </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import Chart, { Annotation } from 'devextreme-react/chart'; class App extends React.Component { render() { return ( <Chart ... > <Annotation type="text" text="Annotation text" /> <Annotation type="image" image="http://image/url/myimage.png" /> </Chart> ); } } export default App;
Annotations can be unattached or anchored to a chart element. The following list shows how to position them. Chart coordinates (argument, value, axis, series) specify the element that the annotation's arrow points to; pixel coordinates (x and y) specify the position of the annotation's center.
Unanchored annotation
annotations: [{ x: 100, y: 200 }]
Annotation anchored to a chart coordinate
annotations: [{ argument: new Date(2019, 1, 16), value: 15, axis: "Value axis 2" // in a chart with multiple value axes }]
Annotation anchored to a series point
annotations: [{ argument: new Date(2019, 1, 16), series: "Series 1" }]
Annotation displayed on an axis
annotations: [{ // An annotation on the argument axis argument: new Date(2019, 1, 16) }, { // An annotation on the value axis value: 15, axis: "Value axis 2" // in a chart with multiple value axes }]
Mixed anchoring (pixel and chart coordinates used simultaneously)
annotations: [{ argument: new Date(2019, 1, 16), y: 200 }]
When a user long-presses an annotation or hovers the mouse pointer over it, the Chart displays a tooltip.
Objects in the annotations[] array configure individual annotations. To specify options common for all annotations, use the commonAnnotationSettings object. Individual settings take precedence over common settings.
See Also
axis
Specifies the name of the value axis on which the value is specified. Useful for a multi-axis chart.
color
This option supports the following colors:
- Hexadecimal colors
- RGB colors
- RGBA colors
- Predefined/cross-browser color names
- Predefined SVG colors
customizeTooltip
The annotation's configuration object.
Set this option to a function that returns an object with the following fields:
color
Specifies the color that fills the tooltip.text
Specifies the tooltip's text.html
Specifies the HTML markup the tooltip displays.NOTEIf you are going to use external resources (for example, images) in the markup, specify the size of the area they occupy.fontColor
Colors the tooltip's text.borderColor
Colors the tooltip's border.
this
keyword.See Also
description
Specifies the annotation's description displayed in the tooltip.
image
Configures the image to be displayed in the annotation. Applies only if the type is "image".
To display an image, assign its URL to the url option. Use the height and width options to resize the image if needed. Otherwise, you can assign the URL directly to the image option.
offsetX
The number assigned to this option specifies the shift in pixels. A negative number shifts the annotation to the left and a positive number shifts it to the right.
See Also
offsetY
The number assigned to this option specifies the shift in pixels. A negative number shifts the annotation up and a positive number shifts it down.
See Also
paddingLeftRight
Along with paddingTopBottom, generates an empty space around the annotation's text or image; specified in pixels.
paddingTopBottom
Along with paddingLeftRight, generates an empty space around the annotation's text or image; specified in pixels.
series
Anchors the annotation to a series point. Accepts the name of the point's series.
Use this option when the annotation is positioned relative to an argument.
For example, the following chart displays two series and an annotation. The annotation is positioned relative to the argument B
but not anchored to any of the two series points that correspond to this argument:
dataSource: [ { arg: "A", val1: 5, val2: 5.5 }, { arg: "B", val1: 3, val2: 6.5 }, { arg: "C", val1: 3.5, val2: 4.5 } ], series: [ { valueField: "val1", name: "Series 1" }, { valueField: "val2", name: "Series 2" } ], annotations: [{ type: "text", text: "Text annotation", argument: "B" }]
To anchor the annotation to one of these series points, specify the annotation's series. For instance, the following code anchors the annotation to the point of Series 1
:
annotations: [{ type: "text", text: "Text annotation", argument: "B", series: "Series 1" }]
See Also
text
Specifies the annotation's text. Applies only if the type is "text".
textOverflow
Specifies what to do with the annotation's text when it overflows the allocated space after applying wordWrap: hide, truncate it and display an ellipsis, or do nothing.
Use the VizTextOverflow
enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Ellipsis
, Hide
, and None
.
tooltipEnabled
A tooltip is a miniature rectangle that appears when a user long-presses an annotation or hovers the mouse pointer over it.
The tooltip displays the contents of the description field or the text or markup returned from the customizeTooltip function. If the description is empty, and customizeTooltip returns nothing, the tooltip does not appear.
Tooltips for annotations and series points have the same appearance specified in the tooltip object. However, you can use the annotation's customizeTooltip function to give the annotation tooltip an individual look.
wordWrap
Specifies how to wrap the annotation's text if it does not fit into a single line.
The following modes are available:
"normal"
Text breaks only at allowed breakpoints (for example, a space between two words)."breakWord"
Words can be broken if there are no available breakpoints in the line."none"
Word wrap is disabled.
If the text overflows the container even after word wrap, the widget applies the textOverflow option.
Use the VizWordWrap
enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Normal
, BreakWord
, and None
.
x
Along with y, positions the annotation's center at a specific pixel coordinate. (0, 0) is the upper left corner of the chart.
y
Along with x, positions the annotation's center at a specific pixel coordinate. (0, 0) is the upper left corner of the chart.
If you have technical questions, please create a support ticket in the DevExpress Support Center.