legends[]

Configures map legends.

Type: Array
Default Value: undefined

A legend is a supplementary map element that helps end-users identify a map area or a map marker. The dxVectorMap widget can display several legends simultaneously. To configure legends, declare an array of objects and assign it to the legends option. Each object in this array specifies settings of one legend. These settings are described in this section.

Each legend requires the source option to be set. This option specifies whether it is areas or markers that must be accompanied with a legend. Learn more from the description of the source option.

A map legend contains several legend items. A legend item consists of a marker and a text. You can change the size of markers using the markerSize option. To provide texts for legend items, you need to implement the customizeText function.

View Demo

backgroundColor

Specifies the color of the legend's background.

Type: String
Default Value: undefined

This option supports the following colors.

  • Hexadecimal colors
  • RGB colors
  • RGBA colors (not supported in Internet Explorer 8)
  • Predefined/cross-browser color names
  • Predefined SVG colors (not supported in Internet Explorer 8)

border

Specifies legend border settings.

Type: Object

This object configures the appearance of the legend border. By default, the legend border is hidden. To make it visible, set the visible option of the border object to true. Then, you can adjust settings of the legend border, such as color, width or opacity using the corresponding options of the border object.

columnCount

Specifies how many columns must be taken to arrange legend items.

Type: Number
Default Value: 0

To arrange legend items, specify how many rows and columns they must occupy. To do this, use the rowCount and columnCount options.

columnItemSpacing

Specifies the spacing between a pair of neighboring legend columns in pixels.

Type: Number
Default Value: 8

customizeHint

Specifies text for a hint that appears when a user hovers the mouse pointer over the text of a legend item.

Type: function(itemInfo)
Function parameters:
itemInfo: Object
Information on a legend item.
Object structure:
start: Number
The start value of the group indicated by the legend item.
end: Number
The end value of the group indicated by the legend item.
index: Number
The index of the group indicated by the legend item.
color: String|undefined
The color of the legend item. This field is undefined if the source is 'markerSizeGroups'.
size: Number|undefined
The diameter of the legend item in pixels. This field is undefined if the source is 'areaColorGroups' or 'markerColorGroups'.
Return Value: String
Text for the hint of the legend item.
Cannot be used in themes.

This option accepts a function that must return the required text. When implementing this function, use its parameter to access information on the legend item.

NOTE: If you have not provided text for legend items using the customizeText option, hints will not appear.

customizeText

Specifies text for legend items.

Type: function(itemInfo)
Function parameters:
itemInfo: Object
Information on a legend item.
Object structure:
start: Number
The start value of the group indicated by the legend item.
end: Number
The end value of the group indicated by the legend item.
index: Number
The index of the group indicated by the legend item.
color: String|undefined
The color of the legend item. This field is undefined if the source is 'markerSizeGroups'.
size: Number|undefined
The diameter of the legend item in pixels. This field is undefined if the source is 'areaColorGroups' or 'markerColorGroups'.
Return Value: String
Text for the legend item.
Cannot be used in themes.

This option accepts a function that returns the text for a legend item. When implementing this function, you can access useful data on the legend item using the function's argument.

font

Specifies font options for legend items.

Type: Object

horizontalAlignment

Specifies the legend's position on the map.

Type: String
Default Value: 'right'
Accepted Values: 'right' | 'center' | 'left'

To position a legend on the map, use this option in conjunction with the verticalAlignment option.

itemsAlignment

Specifies the alignment of legend items.

Type: String
Default Value: undefined
Accepted Values: 'right' | 'center' | 'left'

This option is useful when there is an odd count of items in the legend and they are placed in several columns.

itemTextPosition

Specifies the position of text relative to the item marker.

Type: String
Default Value: undefined
Accepted Values: 'right' | 'left' | 'top' | 'bottom'

margin

Specifies the distance between the legend and the container borders in pixels.

Type: Number|Object
Default Value: 10

When this option is set to a number, the specified margin applies to all sides of the legend. Alternatively, the margin option can be set to an object. This object specifies margins for each side of the legend separately.

Whether or not the specified margin is applied to a particular side of the legend depends on the legend's location. The location is determined by the horizontalAlignment and verticalAlignment options. Refer to the top, bottom, left and right options' description to discover when the margin applies to the corresponding side of the legend.

markerSize

Specifies the size of item markers in the legend in pixels.

Type: Number
Default Value: 12

orientation

Specifies whether to arrange legend items horizontally or vertically.

Type: String
Default Value: undefined
Accepted Values: 'vertical' | 'horizontal'

When this option is set to 'vertical', legend items are displayed vertically (i.e., in a column). When this option is set to 'horizontal', legend items are displayed horizontally (i.e, in a row). When this option is not defined, the legend orientation is chosen automatically.

paddingLeftRight

Specifies the spacing between the legend left/right border and legend items in pixels.

Type: Number
Default Value: 10

paddingTopBottom

Specifies the spacing between the legend top/bottom border and legend items in pixels.

Type: Number
Default Value: 10

rowCount

Specifies how many rows must be taken to arrange legend items.

Type: Number
Default Value: 0

To arrange legend items, specify how many rows and columns they must occupy. To do this, use the rowCount and columnCount options.

rowItemSpacing

Specifies the spacing between a pair of neighboring legend rows in pixels.

Type: Number
Default Value: 8

source

Specifies the source of data for the legend.

Type: String
Default Value: undefined
Accepted Values: 'areaColorGroups'|'markerColorGroups'|'markerSizeGroups'
Cannot be used in themes.

The dxVectorMap's legend supports three types of sources.

  • areaColorGroups
    Can be used if you have grouped map areas in several differently-colored groups. For more information, refer to the area's colorGroupingField and colorGroups option descriptions.

  • markerColorGroups
    Can be used if you have grouped map markers in several differently-colored groups. For more information, refer to the marker's colorGroupingField and colorGroups option descriptions.

  • markerSizeGroups
    Available for markers of a bubble type only. Can be used if you have grouped bubble markers in several groups and specified a size for bubbles in each group. For more information, refer to the sizeGroupingField and sizeGroups option descriptions.

verticalAlignment

Specifies the legend's position on the map.

Type: String
Default Value: 'bottom'
Accepted Values: 'top' | 'bottom'

To position a legend on the map, use this option in conjunction with the horizontalAlignment option.

visible

Specifies whether or not the legend is visible on the map.

Type: Boolean
Default Value: true