VectorMap Configuration

An object that specifies configuration options for the dxVectorMap widget.

areaSettings

An object specifying options for the map areas.

Type: Object

The map areas usually represent geographical objects, such as countries, continents, etc. The appearance of these areas is specified by the options of the areaSettings configuration object. If these options are defined on the first level of the areaSettings object, they are applied to all the map areas at once. However, you can specify several of these options for certain areas exclusively. See the customize option description to learn how.

Show Example:
jQuery

In this example, areas are painted using the 'Vintage' palette. To specify different colors from this palette for the areas, the customize function returns an object that contains the specified palleteIndex field.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
var i = 0;

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            palette: 'Vintage',
            paletteSize: 8,
            customize: function () {
                return {
                    paletteIndex: i++ % 8
                };
            }
        }
    });
});

background

Specifies the options for the map background.

Type: Object

The map background is a space on a map that does not contain areas. Within the background configuration object you can specify colors for the map background and its border.

Show Example:
jQuery

In this example, the background is colored in 'paleturquoise' using the color option. In addition, the background border is colored in 'dodgerblue' using the borderColor option.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        background: {
            borderColor: 'dodgerblue',
            color: 'paleturquoise'
        }
    });
});

bounds

Specifies the positioning of a map in geographical coordinates.

Type: Array| object deprecated
Default Value: undefined

When you need to display only a specific region on a map, rather than the whole thing, specify the geographical coordinates of this region using the bounds option. Assign an array of four values to this option. These values represent geographical coordinates in the following format: [minLongitude, maxLatitude, maxLongitude, minLatitude]. See the image below to discover how these values are applied to the map.

ChartMargin ChartJS

NOTE: Specifying the bounds option with the { minLon: minLongitude, maxLat: maxLatitude, maxLon: maxLongitude, minLat: minLatitude } object is now deprecated.

Show Example:
jQuery

In this example, the map is focused on the USA in code using the bounds array.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
var i = 0;

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/usa.txt',
        areaSettings: {
            palette: 'Ocean',
            paletteSize: 10,
            customize: function () {
                return { paletteIndex: i++ % 10 };
            }
        },
        bounds: [-135, 60, -65, 20]
    });
});

center

Specifies the geographical coordinates of the center for a map.

Type: Array| object deprecated
Default Value: [0, 0]

By default, the map in the dxVectorMap widget is centered on the (0, 0) point. If you need to center the map on a different geographical point, assign an array of two values in the [longitude, latitude] form.

NOTE: Specifying the center with the { lon: longitude, lat: latitude } object is now deprecated.

Show Example:
jQuery

In this example, the map is centered on Africa in code using the center option.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
var i = 0;

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/africa.txt',
        areaSettings: {
            palette: 'Soft',
            paletteSize: 10,
            customize: function () {
                return { paletteIndex: i++ % 10 };
            }
        },
        zoomFactor: 4.5,
        center: [20, 2]
    });
});

centerChanged

Specifies a callback function that is called when the coordinates of the map center are changed.

Type: function(centerCoordinates)
Function parameters:
centerCoordinates: Array
The updated coordinates of the center.

If you need to perform specific actions when the coordinates of the map center are changed, assign a callback function to the centerChanged option. This function will be called every time a user moves the map or when the center is being changed from code by calling the center(centerCoordinates) or viewport(viewportCoordinates) method. When implementing this function, you can use an array of the updated center coordinates passed as the function's parameter.

click

Specifies a callback function that is called when a user clicks on any place on the map.

Type: function(extendedEvent)
Event Handler Argument:
extendedEvent: Object
An extended jQuery event.

When implementing a callback function for this option, use the object that represents the jQuery event extended by the following fields.

  • x
    Contains the X coordinate of the clicked point.
  • y
    Contains the Y coordinate of the clicked point.

This object can be accessed using the function's parameter or the this object.

NOTE: The coordinates are calculated relatively to the client area, i.e., the widget container. To convert them into map coordinates, use the convertCoordinates(x,y) method.

In addition, you can implement functions performing specific actions when an area or marker is being clicked. Assign these functions to the click field of the areaSettings or markerSettings object. Note that in that case, the click function described here will be executed anyway, but only after the click functions of areas or markers are executed.

controlBar

Specifies the options of the control bar.

Type: Object

The control bar is a panel on a map that helps you navigate this map. This panel contains the pan control and the zoom bar for panning and zooming the map correspondingly. You can change the visibility of the control bar and adjust its colors using the options of the controlBar configuration object.

Show Example:
jQuery

In this example, the appearance of the control bar is changed using the controlBar configuration object.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
var i = 0;

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            palette: 'Soft',
            paletteSize: 10,
            customize: function () {
                return { paletteIndex: i++ % 10 };
            }
        },
        controlBar: {
            color: 'cornsilk',
            borderColor: 'goldenrod'
        }
    });
});

drawn

Specifies a callback function that is called when the widget has finished drawing itself.

Type: function(widget)
Function parameters:
widget: Object
The instance of the drawn widget.

If you need to perform specific actions when the widget has finished drawing itself, assign a callback function to the drawn option. When implementing this function, you can access the instance of the currently drawn widget using the function's parameter or the this object.

incidentOccured

Specifies a callback function that is called when an error or warning appears.

Type: function(incidentInfo)
Function parameters:
incidentInfo: Object
Contains information about the occurred incident.

When an error or warning appears, the widget notifies you by passing a message to the browser console. This message contains the ID of the incident, a brief description, and a link to the Errors and Warnings section where further information about this incident can be found. However, you can handle errors and warnings in the way that you require. To do this, implement a callback function performing the required actions and assign it to the incidentOccured option. Within this function, you can use various information about the incident that occurred. This information can be accessed from the fields of the object passed to the callback function as a parameter. These fields are as follows.

  • id
    Contains the ID of the incident. The full list of IDs can be found in the Errors and Warnings section.
  • type
    Contains the type of the incident. This field equals 'error' for errors or 'warning' for warnings.
  • args
    Contains the argument of the incident's message. The content of this field varies greatly, depending on the incident. For example, it may contain the name of the data source field that was not specified correctly, or the name of the option that was not set properly.
  • text
    Contains the text passed to the browser console. This text includes the content of the args field, if there are any.
  • widget
    Contains the name of the widget that produced the error or warning.
  • version
    Contains the currently used version of the ChartJS library.

loadingIndicator

Specifies the appearance of the loading indicator.

Type: Object

Usually, the widget is quick enough to draw itself instantly for a viewer. There are, however, cases, when the widget takes longer to be drawn. In such cases, displaying the loading indicator is recommended. Use the widget's showLoadingIndicator() and hideLoadingIndicator() methods to manage the loading indicator. To specify its appearance, use the loadingIndicator configuration object.

Show Example:
jQuery

In this example, the map options are assigned 3000 ms after the example is loaded. Until that time, the loading indicator is displayed. Its background and font are changed using the backgroundColor and font options respectively. Make a note that these options should be specified at design-time so that the changes are applied at the right time.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
var i = 0;

var mapOptions = {
    mapData: '/Content/data/vectorMap-sources/world.txt',
    areaSettings: {
        palette: 'Bright',
        paletteSize: 10,
        customize: function () {
            return { paletteIndex: i++ % 10 };
        }
    }
};

$(function () {
    $("#mapContainer").dxVectorMap({
        loadingIndicator: {
            backgroundColor: 'lightcyan',
            font: {
                weight: 700,
                size: 16
            }
        }
    }).dxVectorMap('instance').showLoadingIndicator();
});

var configureMap = function () {
    var map = $("#mapContainer").dxVectorMap('instance');
    map.option(mapOptions);
};

setTimeout(configureMap, 3000);

mapData

Specifies a data source for the map area.

Type: Array|String
Default Value: undefined

This option specifies the set of areas represented on a map. To discover different approaches to providing data for map areas, see the Data for Areas topic.

Show Example:
jQuery

Use the drop-down menu below to choose which data source to use for the map. In this example, each data source is represented by a JSON object.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
<div id="selectContainer" style="height:20px;max-width:450px;margin:5px auto;font-family:'Trebuchet MS',Arial,sans-serif;font-size:14px;text-align:center">
    Choose a Data Source for the Map:
    <select id="dropdownListSelector">
        <option value="world">World</option>
        <option value="africa">Africa</option>
        <option value="canada">Canada</option>
        <option value="eurasia">Eurasia</option>
        <option value="europe">Europe</option>
        <option value="usa">USA</option>
    </select>
</div>
var i = 0;

$(function () {
    $('#mapContainer').dxVectorMap({
        areaSettings: {
            palette: 'Soft Pastel',
            paletteSize: 9,
            customize: function () {
                return { paletteIndex: i++ % 9 };
            }
        },
        tooltip: {
            enabled: true,
            customizeTooltip: function () {
                return {
                    text: this.attribute('name')
                };
            }
        },
        mapData: '/Content/data/vectorMap-sources/world.txt'
    });

    $('#dropdownListSelector').change(function () {
        var vectorMap = $('#mapContainer').dxVectorMap('instance');
        vectorMap.option({
            mapData: '/Content/data/vectorMap-sources/' + this.value + '.txt'
        });
    });
});

markers

Specifies a data source for the map markers.

Type: Array|String
Default Value: undefined

Data you need to provide for map markers depends on the type of the markers you use. Generally, you need to declare an array of objects, each of which must hold the coordinates field specifying geographical coordinates of a marker. Additionally, you need to specify the value field (for bubble markers), or the values field (for pie markers), or the url field (for image markers).

For a more comprehensive description of how to provide data for map markers, see the Data for Markers topic.

Show Example:
jQuery

In this example, several markers are displayed on the map. These markers indicate the capitals of ten most populous states in the USA.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
var markers = [
    {
        coordinates: [-121.2808, 38.3320],
        text: 'Sacramento'
    }, {
        coordinates: [-97.75, 30.25],
        text: 'Austin'
    }, {
        coordinates: [-73.7572, 42.6525],
        text: 'Albany'
    }
];

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/usa.txt',
        bounds: [-135, 60, -65, 20],
        zoomFactor: 1.25,
        areaSettings: {
            hoverEnabled: false
        },
        markerSettings: {
            font: { size: 11 }
        },
        markers: markers
    });
});

markerSettings

An object specifying options for the map markers.

Type: Object

A marker is a point on a map accompanied by text that helps you flag places on the map. For example, you can use markers to designate cities on the map. The appearance of the markers is specified by the options of the markerSettings configuration object. If these options are defined on the first level of the markerSettings object, they are applied to all the markers at once. However, you can specify several of these options for certain markers exclusively. See the customize option description to learn how.

Show Example:
jQuery

In this example, each marker is accompanied by a label that displays the name of the state's capital. This name is obtained from the 'name' attribute of the map's data source using the customize option. The font size of the labels is decreased so that the labels do not overlap each other. In addition, the capability to select/deselect a marker by a click is added using the callback function assigned to the click option. When a marker is selected, it is drawn in a color specified by the selectedColor option.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
var markers = [
    {
        coordinates: [-121.2808, 38.3320],
        text: 'Sacramento'
    }, {
        coordinates: [-97.75, 30.25],
        text: 'Austin'
    }, {
        coordinates: [-73.7572, 42.6525],
        text: 'Albany'
    }, {
        coordinates: [-84.2533, 30.455],
        text: 'Tallahassee'
    }, {
        coordinates: [-89.65, 39.783],
        text: 'Springfield'
    }
];

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/usa.txt',
        markers: markers,
        bounds: [-135, 60, -65, 20],
        zoomFactor: 1.25,
        areaSettings: { hoverEnabled: false },
        markerSettings: {
            font: {
                size: 11
            },
            click: function (marker) {
                marker.selected(!marker.selected());
            },
            selectedColor: 'dodgerblue'
        }
    });
});

pathModified

Notifies a widget that it is embedded into an HTML page that uses a path modifier.

Type: Boolean
Default Value: false

If you place a widget on a page that uses a path modifier, notify the widget about it by setting the pathModified option to true. As an example of such modifiers, the base HTML tag can be considered. Also, we recommend you to enable this option if you place the widget inside the <iframe> tag.

rtlEnabled

Specifies whether or not the widget supports right-to-left representation.

Type: Boolean
Default Value: false

The most common scenario is switching all the widgets to a right-to-left reading order. In this instance, set the DevExpress.rtlEnabled field to true. If you need to switch the reading order in a particular widget, use the rtlEnabled configuration option of this widget.

size

Specifies the size of the dxVectorMap widget.

Type: Object

By default, the widget occupies the entire area of the parent container (division). If the container width or height is set to zero, the widget is not displayed.

If you need to set a size for the widget that differs from the container's size, use the size configuration object. Assign a height and width in pixels to the height and width options of the size object.

Show Example:
jQuery

In this example, the size of the dxVectorMap widget is less than the container's size.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto;border:1px solid black"></div>
var i = 0;

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            palette: 'Default',
            paletteSize: 10,
            customize: function () {
                return {
                    paletteIndex: i++ % 10
                };
            }
        },
        size: {
            width: 700,
            height: 400
        }
    });
});

theme

Specifies the name of the theme to be applied.

Type: Object
Default Value: 'desktop'

Use this option to specify the name of the theme that should be applied to the widget. For information on customizing and implementing themes, refer to the Themes topic.

Show Example:
jQuery

This example shows how to implement a custom theme on the base of a predefined one.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
var i = 0;

var greenTheme = {
    name: 'mapGreenTheme',
    map: {
        background: {
            color: 'lightgreen'
        },
        controlBar: {
            borderColor: 'seagreen',
            color: 'darkseagreen'
        }
    }
};

DevExpress.viz.core.registerTheme(greenTheme, 'desktop');

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        theme: 'mapGreenTheme'
    });
});

tooltip

Specifies tooltip options.

Type: Object

A tooltip is a small pop-up rectangle that displays information about an area or a marker when it is hovered over. You can enable or disable a tooltip and change its default appearance using the options of the tooltip configuration object.

Show Example:
jQuery

In this example, tooltips display the name of the area that is currently hovered over. The tooltips' borders are colored in 'royalblue' using the border | color option. In addition, the tooltips' font color is set to 'dodgerblue' using the font | color option.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
var i = 0;

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            palette: 'Ocean',
            paletteSize: 5,
            customize: function () {
                return {
                    paletteIndex: i++ % 5
                };
            }
        },
        tooltip: {
            enabled: true,
            border: { color: 'royalblue' },
            customizeTooltip: function () {
                return {
                    text: this.attribute('name')
                };
            },
            font: {
                color: 'dodgerblue'
            }
        }
    });
});

zoomFactor

Specifies a number that is used to zoom a map initially.

Type: Number
Default Value: 1

Use this option to specify a zoom factor for a map while configuring it. This option accepts a value that is greater than 1. Note that the zooming is performed with relation to the center of the map.

Show Example:
jQuery

In this example, the map is initially zoomed twice as the zoomFactor option is set to 2.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
var i = 0;

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            palette: 'Default',
            paletteSize: 9,
            customize: function () {
                return { paletteIndex: i++ % 9 };
            }
        },
        zoomFactor: 2
    });
});

zoomFactorChanged

Specifies a function that is called when the map zoom factor is changed.

Type: function(zoomFactor)
Function parameters:
zoomFactor: Number
The updated zoom factor.

If you need to perform specific actions when the map zoom factor is changed, assign a callback function to the zoomFactorChanged option. This function will be called every time a user zooms the map or when the zoom factor is changed from code by calling the zoomFactor(zoomFactor) or viewport(viewportCoordinates) method. When implementing this function, you can use the updated value of the map zoom factor passed as the function's parameter.