Hey! This content applies only to previous CARTO products

Please check if it's relevant to your use case. On October 2021 we released a new version of our platform.
You can learn more and read the latest documentation at docs.carto.com

Tutorials  /  Map Styling  /  CartoCSS

CartoCSS Color Mixing Functions

Inside of CARTO Builder we offer a set of default color schemes, CARTOColors, that can be used for both qualitative and quantitative data.

But what about the times when you want to customize the colors on your map, because of its theme, a predefined brand color, or just because? There are a variety of tools and guidelines available to find harmonious color combinations that can be brought into Builder to customize your map.

Another option to get started, that we outline here, is using the CartoCSS color function spin to get started with custom color schemes, particularly for qualitative data.

With the basic building blocks in place, this function can be used in a variety of ways on many different maps. To demonstrate, we’ll generate a series of well-known color harmonies:


Common color harmonies source



The color harmonies in the diagram above, are combinations of two or more colors with a fixed place on the color wheel. Using a base color and spin(), we can create each combination to color features on a map.

The function has two parameters a starting color (@base) and the number of degrees (25) to rotate from that color to define the next:


The degrees range from 0-360 and can be defined as either positive or negative values. Positive values will spin clockwise, and negative, counter-clockwise.

Trees in SF

The maps in this example symbolize a subset of tree species found in the city of San Francisco’s tree species inventory.

Our species of interest are Brisbane Box, Sycamore, and New Zealand Xmas Tree.



Generate color harmonies

Symbolize trees and switch to CartoCSS view


  • we’ll switch the basemap to Dark Matter Lite
  • apply default symbology to the category attribute common_species
  • and then switch to the CartoCSS view of the defined style


Set-up variables

Next, we’ll set up variables that define the styling for each tree type and replace the default category colors in the TurboCARTO ramp with the variable names.

Our base color (#8f44c1) will be defined in @brisbane. @sycamore and @nzxmas we’ll start with a neutral gray (#555).

  • at the top of the stylesheet, add each variable
    @brisbane: #8f44c1;
    @sycamore: #555;
    @nzxmas:   #555;
  • subsititute the colors with our variable names in the TurboCARTO for marker-fill:
    marker-fill: ramp([common_species], (@brisbane, @sycamore, @nzxmas), ("Brisbane Box", "Sycamore", "New Zealand Xmas Tree"), "=");
  • adjust width and line color
    marker-width: 6;
    marker-line-color: #000

screen shot 2018-03-16 at 7 40 15 am

Generate color harmonies

As mentioned above, each color harmony are combinations of two or more colors with a fixed place on the color wheel. Knowing the degrees needed to rotate for each combination, we can easily modify the styling for each variable which in turn will update our map.

Complementary colors

Complementary colors are opposite from each other on the color wheel (180 degrees apart).

Using our base @brisbane, we will set @sycamore to its complementary:

@brisbane:  #8f44c1;
@sycamore:  spin(@brisbane,180);
@nzxmas:    #555;

screen shot 2018-03-16 at 7 39 46 am

Analogous Colors

Analogous colors are directly adjacent to the base color. Typically, at 30 degree intervals on either side.

Below, @sycamore and @nzxmas are analogous to the base, @brisbane.

@brisbane:  #8f44c1;
@sycamore:  spin(@brisbane,30);
@nzxmas:    spin(@brisbane,-30);

screen shot 2018-03-16 at 7 36 21 am


Triadic colors are three, equidistant colors. To get triadic colors from our base, we can divide the color wheel into 3 equal parts.

@brisbane:  #8f44c1;
@sycamore:  spin(@brisbane,(360/3));
@nzxmas:    spin(@brisbane,(-360/3));

screen shot 2018-03-16 at 7 42 22 am

Split Complementary

Split complementary colors use two adjacent colors from the base complementary. We first find the complementary and then find the two adjacent colors that are 30 degrees on either side.

@brisbane: 	#8f44c1;
@sycamore: 	spin(@brisbane,(180+30));
@nzxmas: 	spin(@brisbane,(180-30));

screen shot 2018-03-16 at 8 13 43 am

Change colors!

If you want to experiment with the harmonies with a different base color, simply change the color of your base variable: