ColorRange is a tool that is necessary when we need to identify the value that each point on a map presents. It looks like a range bar, colored as gradient or like a number of colored boxes, each presenting a range of values.

To create a colorrange, use the colorRange() function. There are a lot of parameters might be adjusted, such as orientation (to change it use the orientation() function), size of the color box (use colorLineSize()) or alignment (align() in this case). You can find more about visual settings in the end of this article.

However, first of all we need to adjust the map colors and its ColorScale, because the ColorRange type and appearance depend on those settings. Read the article about ColorScale to know, how to set and adjust it according to your needs.

The first step of adjusting the colors is to set the series and data correctly. Let's make an example with a Choropleth Series Map. Look at the code below.

// set the data
var dataSet =[
    {'id': 'AU.WA', 'value': 300},  // Western Australia
    {'id': 'AU.JB'},                // Jervis Bay Territory
    {'id': 'AU.NS', 'value': 240},  // New South Wales
    {'id': 'AU.VI', 'value': 75},   // Victoria
    {'id': 'AU.NT', 'value': 130},  // Northern Territory
    {'id': 'AU.TS', 'value': 190},  // Tasmania
    {'id': 'AU.CT', labels: false}, // Australian Capital Territory
    {'id': 'AU.SA'},                // South Australia
    {'id': 'AU.QL'}                 // Queensland
// set the map
var map =;

// set the geoData 
// set the series
var series = map.choropleth(dataSet);
// tell the series which field should tie the colorRange and the colorScale together

Here we took an Australia map for the example. You may notice that some regions don't have values, which makes them "unBound", but still all the regions are painted with the default color. That's because we haven't defined the ColorScale yet. If the ColorScale is defined, the unbound regions will become transparent (like in the Ordinal Scale sample).


Note that a ColorRange can only be connected to an only axis, while it's possible to make a map with several series.

Enabling the ColorRange

To enable the ColorRange, there's a simple method colorRange().

// create and enable the colorRange
var cr = map.colorRange(true);

Look at the samples below: we have added the ColorRange to the both previous samples. In the first sample the ColorRange looks like a number of different-colored rectangles because of ordinal Scale. The number of rectangles depends on the number of ranges defined above.


Here is the second case with the linear ColorScale. The ColorRange here looks like a line colored with a gradient.


You may notice that there is a marker on the ColorRange that helps to find the value on the ColorRange.

Visual Settings

There are some visual preferences of a ColorRange that might be set different from the default if needed - such as position, size and other. Look through this paragraph to know more about them.


A simple function orientation() is used for the changing the position. An argument should be a string with one of the following values: 'right', 'left', 'bottom' or 'top'.

// put the colorRange to the right from the map



The ColorRange length adjusting is quite usual: as for any other components, just add the length() method to the colorRange.

// set the colorRange length


Size and position

When you need to change the distance between the ColorRange and the map itself or between the colorRange and the map field borders, use the padding() method. You may define and only argument or all four (if you want them different) for all sides. Look at the following sample:

// set the colorRange padding 

In case you set the only value, this value will be interpreted as the same padding to each of the map field sides.


And if you define all four padding values, you'll be able to change the distance between the ColorKange and both map and its field borders.

// set the colorRange padding 
colorRange.padding(0, 100, 0, -100);


As you can see, the usage of this method with ColorRange is the same as in simple HTML.


To stroke the ColorRange, use the stroke() method. We have already done it before - in the sample with a Bi-polar progression (Ordinal Scale).

// create, enable and stroke the colorRange
var colorRange = map.colorRange();



You can enable, disable, color the labels in different colors, apply some features to format the labels of a colorRange. Use usual labels() method to adjust them.

// disable the labels


You can also create an object:

// adjust the labels
colorRange.labels({'fontSize':10, 'fontColor':'green'});



Marker on a ColorRange is needed to demonstrate the position of the value on a ColorRange, so you can understand the map better. To make any changes with it both ColorRange and marker itself should be enabled.

You can change the marker type, for example:

// change the default marker type to diamond
var marker = colorRange.marker();


Now let's change our marker's color and size:

// change the default marker color to purple

// set the size to your marker


You are looking at an outdated v7 version of this document. Switch to the v8 version to see the up to date information.