Configuration 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
                };
            }
        }
    });
});

borderColor

Specifies a color for the area border.

Type: String
Default Value: '#9d9d9d'

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)
Show Example:
jQuery

In this example, area borders are colored in 'indianred' 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',
        areaSettings: {
            borderColor: 'indianred'
        }
    });
});

borderWidth

Specifies the width of the area border in pixels.

Type: Number
Default Value: 1

Show Example:
jQuery

In this example, the area borders are increased in width up to 3 pixels using the borderWidth option.

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

click

Specifies the function that is called when an area has been clicked.

Type: jQuery.Event
Event Handler Argument:
area: Area
The clicked area.
jQueryEvent: jQuery.Event
The event object.

When implementing a callback function for this option, use the object that represents the area, which has been clicked. To access this object, use the function's first parameter or the this object. The accessible fields and methods of this object are documented in the Area class description within the Map Elements reference section.

In addition, you can access the jQuery-event object using the function's second parameter.

Show Example:
jQuery

In this example, you can select an area by a click.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            hoverEnabled: false,
            selectedBorderColor: 'forestgreen',
            click: function () {
                this.selected(!this.selected());
            }
        }
    });
});

color

Specifies a color for an area.

Type: String
Default Value: '#d2d2d2'

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)
Show Example:
jQuery

In this example, the top ten most populated countries are indicated by the 'yellowgreen' color.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
var mostPopulatedCountries = ['China', 'India', 'United States', 'Indonesia', 'Brazil', 'Pakistan', 'Nigeria', 'Bangladesh', 'Russia', 'Japan'];

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            customize: function () {
                if (jQuery.inArray(this.attributes.name, mostPopulatedCountries) > -1) {
                    return {
                        color: 'yellowgreen'
                    };
                }
            }
        }
    });
});

customize

Specifies the function that customizes each area individually.

Type: function(areaInfo)
Function parameters:
areaInfo: Object
Defines the area to be customized. Represents an object from the mapData array.
Return Value: Area configuration
A configuration object for the area.

When implementing a function for this option, use the fields of the object that represent an area from the data source. To access this object, use the function's parameter or the this object.

The customize function should return the object that contains options to be changed for a certain area. These options are represented in the list below.

Show Example:
jQuery

In this example, the top ten most populated countries are colored in 'dodgerblue' using the color option of the object returned by the customize function. The other countries are colored in 'lightskyblue' using the color option of the areaSettings object.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
var mostPopulatedCountries = ['China', 'India', 'United States', 'Indonesia', 'Brazil', 'Pakistan', 'Nigeria', 'Bangladesh', 'Russia', 'Japan'];

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            color: 'powderblue',
            hoverEnabled: false,
            customize: function () {
                if (jQuery.inArray(this.attributes.name, mostPopulatedCountries) > -1) {
                    return {
                        color: 'dodgerblue'
                    };
                }
            }
        }
    });
});

hoveredBorderColor

Specifies a color for the area border when the area is hovered over.

Type: String
Default Value: '#303030'

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)

NOTE: Make sure that the hoverEnabled option is set to true, so that the hoveredBorderColor option takes effect.

Show Example:
jQuery

In this example, when an area is hovered over, its border is colored in 'lightcoral'.

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

hoveredBorderWidth

Specifies the pixel-measured width of the area border when the area is hovered over.

Type: Number
Default Value: 1

Show Example:
jQuery

In this example, when an area is hovered over, its border has a 4-pixel width.

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

hoveredColor

Specifies a color for an area when this area is hovered over.

Type: String
Default Value: '#d2d2d2'

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)

NOTE: Make sure that the hoverEnabled option is set to true, so that the hoveredColor option takes effect.

Show Example:
jQuery

In this example, when an area is hovered over, it is colored in 'plum'.

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

hoverEnabled

Specifies whether or not to change the appearance of an area when it is hovered over.

Type: Boolean
Default Value: true

If this option is set to true, you can specify colors for the hovered area and its border using the hoveredColor and hoveredBorderColor options, respectively.

Show Example:
jQuery

Toggle the check box below to enable/disable the hovering capability.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
<div id="checkboxContainer" style="height:20px;max-width:300px;margin:10px auto;font-family:'Trebuchet MS',Arial,sans-serif;font-size:14px;text-align:center">
    <input type="checkbox" id="enableHoverCheckbox" checked> Enable Hover
</div>
$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            hoverEnabled: true
        }
    });

    $('#enableHoverCheckbox').change(function () {
        var vectorMap = $('#mapContainer').dxVectorMap('instance');
        vectorMap.option({
            areaSettings: {
                hoverEnabled: this.checked
            }
        });
    });
});

palette

Specifies the name of the palette or a custom range of colors to be used for coloring a map.

Type: Array|String
Default Value: 'default'
Accepted Values: 'Default' | 'Soft Pastel' | 'Harmony Light' | 'Pastel' | 'Bright' | 'Soft' | 'Ocean' | 'Vintage' | 'Violet'

A palette defines a range of colors that are used to paint areas on a map. This range is divided into segments using the value assigned to the paletteSize option. Each segment contributes a color into a resulting array of colors. The more of these segments, the greater the variety of colors in this array. All available palettes are listed in the accepted values.

In order to apply a palette to a map, follow the next steps.

  • Assign the name of the required palette (or an array of two colors) to the palette option.
  • Use the paletteSize option to define how many colors should be produced from the palette or array specified in the previous step.
  • Specify the index of the color from the colors array, which should be used for coloring an area, using the paletteIndex field of the object returned by the customize callback function.
Show Example:
jQuery

Use the drop-down menu below to choose which palette to use for coloring the map.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
<div id="selectContainer" style="height:20px;max-width:350px;margin:5px auto;font-family:'Trebuchet MS',Arial,sans-serif;font-size:14px;text-align:center">
    Choose a Palette:
    <select id="dropdownListSelector">
        <option value="Default">Default</option>
        <option value="Soft Pastel">Soft Pastel</option>
        <option value="Harmony Light">Harmony Light</option>
        <option value="Pastel">Pastel</option>
        <option value="Bright">Bright</option>
        <option value="Soft">Soft</option>
        <option value="Ocean">Ocean</option>
        <option value="Vintage">Vintage</option>
        <option value="Violet">Violet</option>
    </select>
</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
                };
            }
        }
    });

    $('#dropdownListSelector').change(function () {
        var vectorMap = $('#mapContainer').dxVectorMap('instance');
        vectorMap.option({
            areaSettings: {
                palette: this.value
            }
        });
    });
});

paletteSize

Specifies the number of colors in a palette.

Type: Number
Default Value: 0

Assign a number that is greater than 0 to this option in order to use palettes.

Show Example:
jQuery

In this example, you can change the paletteSize option at runtime using the set of radio buttons below the map.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
<div style="height:50px;max-width:500px;margin:5px auto;font-family:'Trebuchet MS',Arial,sans-serif;font-size:14px;text-align:center">
    paletteSize: 
    <input type="radio" name="paletteSize" value="1" checked/> 1 
    <input type="radio" name="paletteSize" value="2" /> 2 
    <input type="radio" name="paletteSize" value="3" /> 3
    <input type="radio" name="paletteSize" value="4" /> 4
    <input type="radio" name="paletteSize" value="5" /> 5
</div>
var i = 0;
var paletteSize = 1;

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

    $("input[name='paletteSize']").change(function () {
        var vectorMap = $('#mapContainer').dxVectorMap('instance');
        paletteSize = +$(this).val();
        i = 0;
        vectorMap.option({
            areaSettings: {
                paletteSize: paletteSize
            }
        })
    });
});

selectedBorderColor

Specifies a color for the area border when the area is selected.

Type: String
Default Value: '#303030'

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)
Show Example:
jQuery

In this example, you can select an area by a click. When the area is selected, its border is colored in 'dodgerblue'.

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

selectedBorderWidth

Specifies the pixel-measured width of the area border when the area is selected.

Type: Number
Default Value: 2

Show Example:
jQuery

In this example, you can select an area by a click. When an area is selected, its border has a 4-pixel width.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            click: function () {
                this.selected(!this.selected());
            },
            selectedBorderWidth: 4
        }
    });
});

selectedColor

Specifies a color for an area when this area is selected.

Type: String
Default Value: '#d2d2d2'

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)
Show Example:
jQuery

In this example, you can select an area by a click. When the area is selected, it is colored in 'lightseagreen'.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            click: function () {
                this.selected(!this.selected());
            },
            selectedBorderColor: 'white',
            selectedColor: 'lightseagreen'
        }
    });
});

selectionChanged

Specifies the function that is called when the selection state of an area has been changed.

Type: function(area)
Function parameters:
area: Area
The area that was selected or unselected.

When implementing a callback function for this option, use the object that represents the area, which has been selected or deselected. To access this object, use the function's parameter or the this object. The accessible fields and methods of this object are documented in the Area class description within the Map Elements reference section.

To identify whether an area has been selected or deselected, call the selected() method of this area. Pass true or false to this method to select or deselect the area.

Show Example:
jQuery

In this example, you can select/deselect areas by a click. When the selection state of an area changes, the corresponding message appears below the map.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
<div style="height:25px;max-width:500px;margin:0px auto;font-family:'Trebuchet MS',Arial,sans-serif;font-size:14px;text-align:center">
    <span id="selectionSpan" />
</div>
$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            click: function () {
                this.selected(!this.selected());
            },
            selectedBorderColor: 'white',
            selectedColor: 'lightskyblue',
            selectionMode: 'multiple',
            selectionChanged: function () {
                this.selected() ? $('#selectionSpan').html(this.attribute('name') + ' has been selected.') : $('#selectionSpan').html(this.attribute('name') + ' has been deselected.');
            }
        }
    });
});

selectionMode

Specifies whether single or multiple areas can be selected on a vector map.

Type: String
Default Value: 'single'
Accepted Values: 'single' | 'multiple' | 'none'

Several options and methods are connected with the selection operation. To specify whether single or multiple areas can be selected at a time, use the selectionMode option. To determine whether a certain area is selected when the widget is created, use the isSelected field of the object returned by the customize callback function.

At runtime, you can do the following operations.

  • Obtain the current selection state of an area using its selected() method.

  • Change the current selection state of an area using its selected(state) method. Pass true or false to this method.

  • Deselect all the selected areas using the clearAreaSelection() method of the map instance.

The change of the selection state invokes the callback function assigned to the selectionChanged option. Within this function you can handle the selection event in the manner you require.

Show Example:
jQuery

Use the drop-down menu below to change the selectionMode option. To see the effect, click one or more map areas.

<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
<div id="selectContainer" style="height:20px;max-width:350px;margin:5px auto;font-family:'Trebuchet MS',Arial,sans-serif;font-size:14px;text-align:center">
    selectionMode:
    <select id="dropdownListSelector">
        <option value="single">single</option>
        <option value="multiple">multiple</option>
        <option value="none">none</option>
    </select>
</div>
$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/world.txt',
        areaSettings: {
            click: function () {
                this.selected(!this.selected());
            },
            selectedBorderColor: 'white',
            selectedColor: 'seagreen',
            selectionMode: 'single'
        }
    });

    $('#dropdownListSelector').change(function () {
        var vectorMap = $('#mapContainer').dxVectorMap('instance');
        vectorMap.option({
            areaSettings: {
                selectionMode: this.value
            }
        });
    });
});