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

Getting started with CartoCSS

CartoCSS is the language that enables you to customize the style of your map data in CARTO. This guide introduces you to CartoCSS and describes how to apply some basic CartoCSS styling to a map layer.

Similar to how Cascading Style Sheets (CSS) are used to style HTML elements on web pages, CartoCSS is used to style different elements of your map data.

Cascading Style Sheets for Maps

The basic structure of CSS code contains:

selector {
  property: value;
}

Where the selector, property, and value are defined in the syntax.

selector specifies the HTML element that you are applying style to.
property of the selector element, that you are modifying the style of.
value defines how you want the property to appear.

CartoCSS enables you to control styles specifically for attributes of your data.

#layer {
  polygon-fill: #ffcc00;
}

Where the selector, property, and value are defined in the syntax.

#layer defines the map layer being styled.
polygon-fill is the property of the selector element, that you are modifying the style of.
#ffcc00 is the value that defines how you want the property to appear.

CartoCSS Properties and Values

The STYLE tab of a selected map layer displays how the associated CartoCSS styling is processed behind the scenes.

Import the template .carto file packaged from the “Download resources” of this guide and create the map. Builder opens displaying a single map layer and default styling, based on the data.

Click on “Download resources” from this guide to download the zip file to your local machine. Extract the zip file to view the .carto file(s) used for this guide.
Select the Null Island Election map layer to view the STYLE tab.
From the STYLE tab, click the slider button from VALUES to CARTOCSS.

Default CartoCSS applied to map layer

The CartoCSS syntax defines the properties of color, opacity, and line-width for the polygon. Its values include the polygon-fill and line-color defined with hexadecimal codes, opacity values ranging from 0 (fully transparent) to 1 (fully opaque), and line-width for the stroke measured in pixels. It also includes the blending mode for the composite operation, that defines how the line interacts with the polygon.

#layer {
  polygon-fill: #374C70;
  polygon-opacity: 0.9;
  polygon-gamma: 0.5;
  line-color: #FFF;
  line-width: 1;
  line-opacity: 0.5;
  line-comp-op: soft-light;
}

CHEATSHEET: Blending Overlapping Geometries

Blending values are style options that effect the way colors of overlapping geometries interact with each other on the Map View. Color blending is applied to the specific symbolizer property, depending on the blending mode you are trying to achieve.

none: No color blending styling is applied to the map layer. This is the default option.
multiply: Multiply literally multiplies the color of the top layer by the color of each layer beneath, which typically results in the overlapping areas becoming darker.
screen: Similar to Multiply, screen multiplies the overlapping areas. Unlike multiply, it subtracts the multiplied color channel numbers from their added value to invert them. This makes the overlapping areas brighter. If white is used, it will not change appearance. Black areas will disappear. Use this when you want to lighten overlapping areas in your map.
overlay: Overlay is a color blend mode that combines multiply and screen composite operations. Black appears as dark, as it originally is in its layer; white appears as bright, as it originally is in its layer. How purely other colors are rendered depends on how close they are to white or black. The closer a color is in value to pure midtone gray, the less it will appear. Use this when you want to show both light and dark in your overlapping layers.
darken: Darken has a similar effect to multiply, but is more extreme. As it applies the color from the base layer to the target layers, it compares each to find the darkest-colored pixels and keeps those.
lighten: Lighten works the same way as darken, but inversely. The lightest-colored pixels from each layer are kept, and if pixels are darker than the base layer, then the base layer color replaces them. This can be useful when you want to change the color of your overlapping areas shadows.
color-dodge: The color-dodge color blend mode is similar to screen but the overall effect is more extreme. Your elements become much brighter (except if your base layer is black). Darker areas are tinted towards the source color. Use this when you want to have a major lightening effect with extreme contrast between your layers, without much detail showing.
color-burn: Color-burn works similarly to color-dodge, but has a darkening effect. It increases the contrast between base and target layers, with pixels in your overlapping area tinted towards the source color. Use this when you want a darkening effect with more contrast than multiply or darken.
xor: Xor is an alpha composite operation that shows both the base and target layers, but only the parts that do not overlap each other.
src-over: Source-over is also an alpha composite operation that keeps the full transparency of both the base and target layers. The visual effect is that the base layer shows on top of all layers involved in the overlap area.

Additional blending options can be applied with CartoCSS syntax. View the complete list of CartoCSS values and see example effects of these blending options.

Other CartoCSS Properties

Apply some basic custom properties so that you can see how CartoCSS styling works. For this example, the CartoCSS syntax modifies the fill color and opacity of the polygon, and also applies line-dasharray; which specifies comma-separated values to define the pattern between the outline or stroke of the polygon.

Copy and paste the following CartoCSS syntax to the STYLE tab.
```
 #layer {
    polygon-fill: #FF5C00;
    polygon-opacity: 0.7;
    line-color: #FFFFFF;
    line-width: 0.5;
    line-opacity: 1;
    line-dasharray: 10, 5;
 }
```
For the line-dasharray property, the first number value 10 is the dash length of the line. The second number 5 is the width of the space between dashes. You can enter additional, comma-separated values to specify multiple dash lengths and gaps for a more complex pattern.
Click APPLY and note how the map styling changes.

Once you apply custom CartoCSS styling for any map layer, you cannot switch back to the VALUES selections; unless you clear the CartoCSS styling applied. Your custom styling will be removed.

CartoCSS Conditional Styling

You can apply CartoCSS properties to the overall map layer, or to specific map data.

To apply CartoCSS styling to a category of data, apply brackets containing a column name winning_party from your map layers dataset, and specify only the column value that the style should be applied to Nada.
```
#layer {
 [winning_party = 'Nada']{
   polygon-fill: #FFA300;
 }

 [winning_party = 'Nix']{
   polygon-fill: #F11810;
 }
}
```

While you can apply CartoCSS styles to different layers on a map, it is highly recommended that you view the suggested best practices for applying CartoCSS syntax more effectively.

Image Fills with CartoCSS

You can include an image file as part of a fill pattern.

Apply polygon-pattern-file, which uses an image url for its value, and fills polygon with a tiled picture.
Change the image fill opacity using the polygon-pattern-opacity property. If less than maximum opacity is used in combination to a polygon-fill color, the color appears underneath the image fill layer.

The complete CartoCSS syntax for these steps appears as follows. Copy and paste to the STYLE tab and apply the code to visualize how an image url is applied as a pattern.

  #layer {
     polygon-opacity: 0.7;
     polygon-pattern-file: url(https://s3.amazonaws.com/com.cartodb.users-assets.production/production/stephaniemongon/assets/20150607041630diag-w.png);
     polygon-pattern-opacity: 0.3;
     line-color: #FFFFFF;
     line-width: 0.5;
     line-opacity: 1;
     line-dasharray: 10, 5;

     [winning_party = 'Nada']{
       polygon-fill: #FFA300;
     }

     [winning_party = 'Nix']{
       polygon-fill: #F11810;
     }
   }

Download the final .carto file, packaged from the “Download resources” of this guide, to view how all of the CartoCSS syntax was applied to this map. Additionally, note that the basemap was changed to enhance the background of the map against the applied styling. The final map also contains a legend, which include symbols and text to describe your map data.

CartoCSS Resources

Use the following resources to reference the library of CartoCSS properties, or view the other guides for more advanced styling examples using CartoCSS.