Language Elements¶

Color¶

CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, hsluv, and hsluva. It also supports the predefined HTML colors names, like yellow and blue.

#line {
  line-color: #ff0;
  line-color: #ffff00;
  line-color: rgb(255, 255, 0);
  line-color: rgba(255, 255, 0, 1);
  line-color: hsl(100, 50%, 50%);
  line-color: hsla(100, 50%, 50%, 1);
  line-color: hsluv(100, 50%, 50%); // same values yield different color than HSL
  line-color: hsluva(100, 50%, 50%, 1);
  line-color: yellow;
}

Especially of note is the support for HSL and HSLuv, which can be easier to reason about than RGB. CartoCSS also includes several color operation functions borrowed from LessCSS:

// lighten and darken colors
lighten(#ace, 10%);
darken(#ace, 10%);

// saturate and desaturate
saturate(#550000, 10%);
desaturate(#00ff00, 10%);

// increase or decrease the opacity of a color
fadein(#fafafa, 10%);
fadeout(#fefefe, 14%);

// spin rotates a color around the color wheel by degrees
spin(#ff00ff, 10);

// mix generates a color in between two other colors.
mix(#fff, #000, 50%);

// get color components
hue(#ff00ff);
saturation(#ff00ff);
lightness(#ff00ff);
alpha(hsla(100, 50%, 50%, 0.5));

These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in a functionp-variant (e.g. lightenp), which force a given color into HSLuv color space.

Float¶

Float is a fancy way of saying ‘number’. In CartoCSS, you specify just a number - unlike CSS, there are no units, but everything is specified in pixels.

#line {
  line-width: 2;
}

It’s also possible to do simple math with number values:

#line {
  line-width: 4 / 2; // division
  line-width: 4 + 2; // addition
  line-width: 4 - 2; // subtraction
  line-width: 4 * 2; // multiplication
  line-width: 4 % 2; // modulus
}

URI¶

URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of url('place.png') notation that you would with HTML. Quotes around the URL aren’t required, but are highly recommended. URIs can be paths to places on your computer, or on the internet.

#markers {
  marker-file: url('marker.png');
}

String¶

A string is basically just text. In the case of CartoCSS, you’re going to put it in quotes. Strings can be anything, though pay attention to the cases of text-name and shield-name - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below.

#labels {
  text-name: "[MY_FIELD]";
}

Boolean¶

Boolean means yes or no, so it accepts the values true or false.

#markers {
  marker-allow-overlap: true;
}

Expressions¶

Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of ‘fields’, where you’d specify "[FIELD]", but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within CartoCSS syntax.

#buildings {
  building-height: [HEIGHT_FIELD] * 10;
}

Numbers¶

Numbers are comma-separated lists of one or more number in a specific order. They’re used in line dash arrays, in which the numbers specify intervals of line, break, and line again.

#disputedboundary {
  line-dasharray: 1, 4, 2;
}

Percentages¶

In CartoCSS, the percentage symbol, % universally means value/100. It’s meant to be used with ratio-related properties, like opacity rules.

In an example:

#world {
  // this syntax
  polygon-opacity: 50%;

  // is equivalent to
  polygon-opacity: 0.5;
}

Functions¶

Functions are comma-separated lists of one or more functions. For instance, transforms use the functions type to allow for transforms within CartoCSS, which are optionally chainable.

#point {
  point-transform: scale(2, 2);
}

Mapnik Render-Time Variables¶

Mapnik >= 3.0.0 supports variables of the form @var. These can be used from CartoCSS by specifying them as strings. For example:

#layer {
  line-width: '@zoom';
}

For this to have any effect you have to pass the variables to Mapnik at render time in a hashmap of the form variable_name:variable_value.

Controlling output of symbolizers and symbolizer attributes¶

You can control symbolizer output by using rules that work on the whole symbolizer. E.g. line works on the line symbolizer. By using the keywords none or auto you can either suppress the symbolizer or output it with default values. The keyword auto does not work on shield and text symbolizers because they have attributes without default values. Here is an example how this works:

#layer {
  line: none;
  line-width: 2;
  [feature = 'redfeature'] {
    line-color: red;
  }
  [feature = 'bluefeature'] {
    line-color: blue;
  }
}

Without line: none carto would output a line symbolizer with default values for all features other than redfeature and bluefeature, that is a black line with width 1. In contrast, you can quickly output a symbolizer with default value by using auto:

#layer {
  [feature = 'quickfeature'] {
    marker: auto;
  }
}

This outputs a default markers symbolizer for all quickfeature features.

You can also control the output of individual symbolizer properties by specifying them with the keyword none e.g. line-color: none. They will then be removed from the symbolizer thus using their default value or not using them at all. This does not work or makes sense for all properties like e.g. not for text-face-name as it does not have a default value. For an overview over properties where this works or makes sense see this list. In this case the use of none and auto is equivalent. In both cases the default value will be used as Mapnik uses the default value automatically when the property is not present.