Basic CartoCSS for Map Styling

Styling Guides

Basic CartoCSS for Map Styling

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.

  1. 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.
  2. Select the Null Island Election map layer to view the STYLE tab.

  3. 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;
}

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.

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

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

  1. Apply polygon-pattern-file, which uses an image url for its value, and fills polygon with a tiled picture.

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