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).

JsFiddle Playground

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.

JsFiddle Playground

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

JsFiddle Playground

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

JsFiddle Playground


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

	// set the colorRange length

JsFiddle Playground

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.

JsFiddle Playground

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

JsFiddle Playground

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();

JsFiddle Playground


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

JsFiddle Playground

You can also create an object:

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

JsFiddle Playground


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();

JsFiddle Playground

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

	// change the default marker color to purple
	// set the size to your marker

JsFiddle Playground

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