JavaScript/jQuery VectorMap - annotations
Annotations are containers for images, text blocks, and custom content that display additional information about the visualized data.
To create annotations, assign an array of objects to the annotations[] property. Each object configures an individual annotation. You can set each annotation's type property to "text", "image", or "custom". Depending on the type, specify the annotation's text, image, or template property:
jQuery
$(function() {
$("#vectorMap").dxVectorMap({
annotations: [{
type: "text",
text: "Annotation text"
}, {
type: "image",
image: "http://image/url/myimage.png"
}, {
type: "custom",
template: function(annotation) {
const data = annotation.data;
const $svg = $("<svg>");
// ...
// Customize the annotation's markup here
// ...
return $svg;
}
}]
});
});Angular
<dx-vector-map ... >
<dxi-annotation
type="text"
text="Annotation text">
</dxi-annotation>
<dxi-annotation
type="image"
image="http://image/url/myimage.png">
</dxi-annotation>
<dxi-annotation
type="custom"
template="custom-annotation">
</dxi-annotation>
<svg *dxTemplate="let annotation of 'custom-annotation'">
<!-- Declare custom SVG markup here -->
</svg>
</dx-vector-map>
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 { DxVectorMapModule } from 'devextreme-angular';
@NgModule({
declarations: [
AppComponent
],
imports: [
BrowserModule,
DxVectorMapModule
],
providers: [ ],
bootstrap: [AppComponent]
})
export class AppModule { }Vue
<template>
<DxVectorMap ... >
<DxAnnotation
type="text"
text="Annotation text"
/>
<DxAnnotation
type="image"
image="http://image/url/myimage.png"
/>
<DxAnnotation
type="custom"
template="custom-annotation"
/>
<template #custom-annotation="{ data }">
<svg>
<!-- Declare custom SVG markup here -->
</svg>
</template>
</DxVectorMap>
</template>
<script>
import DxVectorMap, {
DxAnnotation
} from 'devextreme-vue/vector-map';
export default {
components: {
DxVectorMap,
DxAnnotation
},
data() {
// ...
}
}
</script>React
import React from 'react';
import VectorMap, {
Annotation
} from 'devextreme-react/vector-map';
function CustomAnnotation(annotation) {
const data = annotation.data;
return (
<svg>
{/* Declare custom SVG markup here */}
</svg>
);
}
export default function App() {
return (
<VectorMap ... >
<Annotation
type="text"
text="Annotation text"
/>
<Annotation
type="image"
image="http://image/url/myimage.png"
/>
<Annotation
type="custom"
render={CustomAnnotation}
/>
</VectorMap>
);
}Annotations can be positioned at specific geographic coordinates or coordinates of the client area:
Geographic coordinates
annotations: [{ coordinates: [-75.4999, 43.00035] }]Client area coordinates (x and y)
annotations: [{ x: 100, y: 200 }]
When a user long-presses an annotation or hovers the mouse pointer over it, the VectorMap displays a tooltip.
Objects in the annotations[] array configure individual annotations. To specify properties common for all annotations, use the commonAnnotationSettings object. Individual settings take precedence over common settings.
See Also
color
This property supports the following colors:
- Hexadecimal colors
- RGB colors
- RGBA colors
- Predefined/cross-browser color names
- Predefined SVG colors
- Paint server address
component
An alias for the template property specified in React. Accepts a custom component. Refer to Using a Custom Component for more information.
customizeTooltip
The annotation's configuration object.
This property should be assigned a function that returns an object with the following fields:
| Field name | Description |
|---|---|
text |
The tooltip's text. |
html |
The HTML markup displayed in a tooltip. The VectorMap evaluates the markup. Make sure that it does not contain malicious code. Refer to the following help topic for more information: Potentially Vulnerable API - customizeTooltip. To use external resources (for example, images) in the markup, specify the size of the area they occupy beforehand. |
color |
The tooltip's color. |
fontColor |
The color of the tooltip's text. |
borderColor |
The color of the tooltip's border. |
this keyword.See Also
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 property and use the height and width properties to resize the image. Otherwise, assign the URL directly to the image property.
offsetX
The number assigned to this property 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 property specifies the shift in pixels. A negative number shifts the annotation up and a positive number shifts it down.
See Also
paddingLeftRight
Used with paddingTopBottom to generate 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.
render
An alias for the template property specified in React. Accepts a rendering function. Refer to Using a Rendering Function for more information.
template
Specifies a custom template for the annotation. Applies only if the type is "custom".
jQuery
$(function() {
$("#vectorMap").dxVectorMap({
annotations: [{
// ...
type: "custom",
template: function(annotation) {
const data = annotation.data;
const $svg = $("<svg>");
// ...
// Customize the annotation's markup here
// ...
return $svg;
}
}]
});
});Angular
<dx-vector-map ... >
<dxi-annotation ...
type="custom"
template="custom-annotation">
</dxi-annotation>
<svg *dxTemplate="let annotation of 'custom-annotation'">
<!-- Declare custom SVG markup here -->
</svg>
</dx-vector-map>Vue
<template>
<DxVectorMap ... >
<DxAnnotation ...
type="custom"
template="custom-annotation"
/>
<template #custom-annotation="{ data }">
<svg>
<!-- Declare custom SVG markup here -->
</svg>
</template>
</DxVectorMap>
</template>
<script>
import DxVectorMap, {
DxAnnotation
} from 'devextreme-vue/vector-map';
export default {
components: {
DxVectorMap,
DxAnnotation
},
data() {
// ...
}
}
</script>React
import React from 'react';
import VectorMap, {
Annotation
} from 'devextreme-react/vector-map';
function CustomAnnotation(annotation) {
const data = annotation.data;
return (
<svg>
{/* Declare custom SVG markup here */}
</svg>
);
}
export default function App() {
return (
<VectorMap ... >
<Annotation ...
type="custom"
render={CustomAnnotation}
/>
</VectorMap>
);
}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.
tooltipComponent
An alias for the tooltipTemplate property specified in React. Accepts a custom component. Refer to Using a Custom Component for more information.
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 as specified in the tooltip object. You can use the annotation's customizeTooltip function to customize the annotation tooltip.
tooltipRender
An alias for the tooltipTemplate property specified in React. Accepts a rendering function. Refer to Using a Rendering Function for more information.
type
Specifies whether the annotation displays text, an image, or a template. This is a required setting.
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 UI component applies the textOverflow property.
x
Used with y to position the annotation's center at a specific pixel coordinate. (0, 0) is the upper left corner of the UI component.
y
Used with x to position the annotation's center at a specific pixel coordinate. (0, 0) is the upper left corner of the UI component.