Map Elements

This guide provides a detailed overview of dxVectorMap elements. Each topic in this guide contains a brief description of an element and its main features, which can be configured.

Below is the element map of the dxVectorMap widget. It may be helpful as you begin learning the capabilities of this widget. Hover over an element on the map to discover the name of this element. A click on an element navigates you to a topic devoted to this element.

DevExtreme dxVectorMap Elements

Areas

An area is the fundamental element of the dxVectorMap widget. Map areas usually represent geographical objects, such as countries, continents, etc.

DevExtreme ChartJS VectorMap

See Also

Areas are generated on the base of the data source assigned to the mapData option. For more information on providing data for map areas, refer to the Data for Areas topic.

You can configure map areas using fields of the areaSettings object.

JavaScript
var vectorMapOptions = {
    // ...
    areaSettings: {
        // area settings are specified here
    }
};

The following list provides a brief overview of area features that can be configured using this object.

  • Color
    You can specify colors for areas using the color option and for their borders using the borderColor option. In addition, you can use a palette to colorize your map. Using a palette requires several options to be specified. To get a step-by-step guide on applying a palette to your map, refer to the palette option description.

  • Appearance in the Hovered State
    When a user hovers the mouse pointer over an area, this area enters the hovered state. You can specify a color for an area in this state using the hoveredColor option. Additionally, you can change the appearance of the area border using the hoveredBorderColor and hoveredBorderWidth options.

  • Appearance in the Selected State
    If you have implemented the selection capability in your map, customize the appearance of areas in the selected state. Similarly to the appearance of areas in the hovered state, you can specify a color for areas in the selected state using the selectedColor option, and a color and a width for the area border using the selectedBorderColor and selectedBorderWidth options.

Specified directly in the areaSettings object, these options are applied to all map areas. To set them for specific areas, determine these options in the object returned by the customize function. When implementing this function, use an Area object to recognize a particular area. This object is passed to the customize function as the argument.

JavaScript
var vectorMapOptions = {
    // ...
    areaSettings: {
        customize: function (area) {
            if (area.attribute('name') == 'France')
                return { color: 'blue' } // paints the 'France' area in blue
        }
    }
};

The Area object represents a map area and provides access to the attributes and the state of the area. To obtain an array of Area objects, use the getAreas() method. To learn fields and methods of the Area object that you can utilize, refer to the description of this object.

Show Example:
jQuery

In this example, a palette is used to colorize map areas. However, for the 'Canada' area, a color is set explicitly within the customize function. Additionally, specific appearances are set for areas in the hovered and selected state.


                                    

                                    

Area Labels

An area label is a text that accompanies a map area. Usually, an area label displays the name of a certain geographical object, such as a country, a continent, etc. A label disappears when its area is too small and the text does not fit it. To see the small area labels, zoom in the map.

Area Labels

You can configure area labels using fields of the areaSettings | label object.

JavaScript
var vectorMapOptions = {
    // ...
    areaSettings: {
        label: {
            // area labels settings are specified here
        }
    }
};

Map data format allows you to set a number of attributes for each map area. Make sure your map data provides an attribute that can be used for labeling. To use the information provided by this attribute in a label, assign the attribute name to the areaSettings | label | dataField option. The predefined data sources already include the 'name' attribute containing the geographical name of areas.

If you use a JSON object or a Binary Source as your map data, make sure the field you need to use for area labels is recognized by the attribute(name) method correctly.

To display area labels on a map, set the areaSettings | label | enabled option to true. Also you can customize the text appearance using the font object.

Show Example:
jQuery

Markers

A marker is a point on a map accompanied by text that helps you flag certain places on the map. For example, you can use map markers to designate cities.

Four types of markers are available in dxVectorMap: dot, bubble, pie and image, each of which corresponds to particular representational needs. The image below demonstrates the appearance of each marker type. Note that despite the fact that this image depicts all four types of markers on one map, an actual dxVectorMap can contain markers of only one type at a time.

DevExtreme ChartJS VectorMap

See Also

Markers are generated on the base of the data source assigned to the markers option. Different marker types require different data to be provided. For more information on how to provide data for map markers, refer to the Data for Markers topic.

You can configure map markers using fields of the markerSettings object. To specify the type of markers, set the type field of this object.

JavaScript
var vectorMapOptions = {
    // ...
    markerSettings: {
        // ...
        type: 'bubble' // 'dot' | 'pie' | 'image'
    }
};

The majority of marker features are configured using options that are common for all marker types. However, there are some features peculiar to a particular marker type. These features are configured using options specific for this marker type.

The following list gives an overview of the main features of all marker types and options that control them.

  • Label
    To specify the text that accompanies a map marker, use the marker's text option. You can disable all marker labels by setting the label | enabled option to false. Also you can configure the label's font using the label | font object.

  • Color
    You can specify the color of dot and bubble markers using the color option. To colorize pie markers, set the palette option instead. Additionally, you can change the color of the marker border using the borderColor option.

  • Size
    To specify the diameter of dot and pie markers in pixels, set the size option. The size of bubble markers cannot be specified explicitly, as it depends on the value a particular bubble marker represents. Instead, you can specify the size of the smallest and the largest bubbles. For this purpose, use the minSize and maxSize options.

  • Appearance in the Hovered State
    When a user hovers the mouse pointer over a marker, this marker enters the hovered state. You can specify the color of a dot or bubble marker in this state using the hoveredColor option. Additionally, you can change the appearance of the marker border using the hoveredBorderColor and hoveredBorderWidth options.

  • Appearance in the Selected State
    If you have implemented the selection capability in your map, customize the appearance of markers in the selected state. Similarly to the appearance of markers in the hovered state, you can specify a color for dot and bubble markers in the selected state using the selectedColor option and the appearance of the marker border using the selectedBorderColor and selectedBorderWidth options.

Specified directly in the markerSettings object, these options are applied to all map markers. To set them for specific markers, determine these options in the object returned by the customize function. When implementing this function, use a Marker object to recognize a particular marker. This object is passed to the customize function as the argument.

JavaScript
var vectorMapOptions = {
    // ...
    markerSettings: {
        customize: function (marker) {
            if (marker.text == 'Austin')
                return { color: 'blue' } // paints the 'Austin' marker in blue
        }
    }
};

The Marker object represents a map marker and provides access to the attributes and the state of the marker. To obtain an array of Marker objects, use the getMarkers() method. To learn fields and methods of the Marker object that you can utilize, refer to the description of this object.

Show Example:
jQuery

In this example, a color is set for all markers using the markerSettings | color option. Note that a different color and size are set for the "Albuquerque" marker using the customize function. Additionally, particular appearances are specified for markers in the hovered and selected state.


                                    

                                    

Control Bar

A control bar is a map element that supplies a user with the capability of navigating a map. This element resides on the left side of the map. The control bar consists of a pan control and a zoom bar, which provide the panning and zooming capabilities to the user.

DevExtreme ChartJS VectorMap

Control bar settings are specified using fields of the controlBar object.

JavaScript
var vectorMapOptions = {
    // ...
    controlBar: {
        // control bar settings are specified here
    }
};

The following list provides an overview of control bar properties configurable within this object.

  • Visibility
    The control bar is visible by default, but if you need to hide it, set the enabled option to false.

  • Color
    You can specify individual colors for the outline and the inner area of the control bar elements using the borderColor and color options respectively.

Tooltips

A tooltip is a small popup rectangle containing information about an area or a marker when a user hovers the mouse pointer over it. In common cases, a tooltip is required to display the name of the area or marker. However, it can display any information you may find useful.

DevExtreme ChartJS VectorMap

Tooltips are configured using fields of the tooltip object. By default, they are disabled. To enable them, assign true to the enabled field of the tooltip object.

JavaScript
var vectorMapOptions = {
    // ...
    tooltip: {
        enabled: true
    }
};

Then, you are required to specify the text to be displayed by a tooltip. Implement a function returning an object with the text field set and assign this function to the customizeTooltip option. When implementing it, you can use an Area or Marker object passed to this function as the argument. To distinguish areas from markers, check the type field of this object against being equal to 'area' or 'marker'. For example, the following code snippet shows how to provide text only for marker tooltips.

JavaScript
var vectorMapOptions = {
    // ...
    tooltip: {
        // ...
        customizeTooltip: function (element) {
            if (element.type == 'marker') {
                return { text: element.text };
            }
        }
    }
};

Furthermore, there is a number of additional options specifying the appearance of tooltips. All of them are set in the tooltip configuration object. A structured overview of these options is given in the following list.

  • Color
    You can specify the color of tooltips using the color option. If you need to specify the color of a particular tooltip, assign it to the color field of the object returned by the customizeTooltip function.

  • Font Settings
    To change the font of the text displayed by a tooltip, use fields of the font object.

  • Border Appearance
    You can change the visibility, color, width and other settings of the tooltip border using fields of the border configuration object.

  • Shadow
    Tooltips are displayed casting a small shadow. To specify its blurriness, opacity, color and other settings, use shadow object fields.

Show Example:
jQuery

In this example, a tooltip appears when you hover the mouse pointer over an area. This behavior is specified by the enabled and customizeTooltip options of the tooltip object. In addition, the appearance of tooltips is adjusted.


                                    

                                    

Legend

A legend is a supplementary map element that helps end-users identify a map area or a map marker.

DevExtreme ChartJS VectorMap

The dxVectorMap widget can display several legends simultaneously. To configure the legends of your map, define one or more elements of the legends array.

JavaScript
var vectorMapOptions = {
    // ...
    legends: [{
        // First legend configuration
    }, {
        // Second legend configuration
    }]
};

To display a legend, define its source option according to the legend's purpose and assign the function that will generate the legend labels to the customizeText option of the legend.

JavaScript
var vectorMapOptions = {
    // ...
    legends: [{
        source: "areaColorGroups",  // or 'markerColorGroups' or 'markerSizeGroups'
        customizeText: function (arg) {
            // Return a text according to arg
        }
    }]
};

The following list provides a brief overview of legend features that can be configured using the elements of the legends array.

  • Visibility
    To hide the configured legend, set the visible option to false.

  • Location
    Use the horizontalAlignment and verticalAlignment options to specify the legend's position on the map. In addition, you can change the interval between the legend and the map edges using the margin object.

  • Appearance
    Use the backgroundColor option and the border object to configure the legend's appearance. You can also customize the legend's font using the font object.

  • Items Layout
    Legend items can be placed in a row or a column. To specify how to arrange items, use the orientation option. There can also be several rows and columns in a legend. To set the number of rows and columns to be used, use the legend's rowCount and columnCount options. These rows and columns will be placed within a legend separated by a space between each other, and from the legend's border. To specify the spacing parameters, use the legend's rowltemSpacing, columnltemSpacing, paddingLeftRight and paddingTopBottom options.

  • Hint
    In addition to the text label describing a legend item, you can specify hints which will appear when the item is hovered. Assign the function that will generate hints to the customizeHint option.

Show Example:
jQuery