Your search returned no results

Try another search term or view Stack Exchange, where we have active conversations with Developers about GIS.

    http://gis.stackexchange.com/
    Support channel in Stack Exchange

    Thousands of developers around the world have helped make CartoDB a success, and we have active conversations with them about GIS in Stack Exchange.

    Go to Stack Exchange

    CartoCSS Best Practices

    While there are many ways to apply the same visual effects with CartoCSS properties, this section describes the most efficient and intuitive methods for structuring your CartoCSS syntax.

    You can apply CartoCSS properties to the overall map style, or to specific map symbolizers (such as markers and points). Sometimes, applying properties to a symbolizer is not the most effective workflow for enhancing your overall map style. Other times, applying a style to the overall map is not rendered if there is no default value defined, and thus, not needed. For example, see how composite operations can be used for color blending, based on style or symbolizer.

    When applying CartoCSS syntax, it helps to understand how values are applied to your map:

    • The source is where the style is applied (either as a value or as a symbolizer property)
    • The destination is the effect on the rest of the map, underneath the source
    • Any layers that appear above the source are unaffected by the applied style and are rendered normally
    • Typically, you apply CartoCSS properties to different layers on a map. You can add multiple styles and values for each layer

    • Alternatively, you can apply CartoCSS by nesting categories and values. Categories contain multiple values listed under the same, single category using brackets { }. This enables you visualize all of the styling elements applied to the overall map or to individual symbolizers, and avoid adding any redundant or unnecessary parameters. This is the suggested method if you are applying styles to a multi-scale map.

    Note: Be mindful when applying styles to a map with multiple layers. Instead of applying an overall style to each map layer, apply the style to one layer on the map using this nested structure. For example, suppose you have a map with four layers, you can define zoom dependent styling as a nested value in one map layer. You do not have to go through each layer of the map to apply a zoom style. Using the nested structure allows you to apply all of the styling inside the brackets { }. This is a more efficient method of applying overall map styling.

    Each of the examples below produces the same visual effect. Note how the CartoCSS syntax is structured.

    Example 1: CartoCSS syntax structured by point

    Marker fill values are applied to the overall style of the map. Each map point is labeled #continent_points[continent="name"] { and contains its own marker-fill style.

    #continent_points {
      marker-fill-opacity: 0.9;
      marker-line-color: #FFF;
      marker-line-width: 1;
      marker-line-opacity: 1;
      marker-placement: point;
      marker-type: ellipse;
      marker-width: 10;
      marker-allow-overlap: true;
    }
    #continent_points[continent="Africa"] {
      marker-fill: #A6CEE3;
    }
    #continent_points[continent="Antarctica"] {
      marker-fill: #1F78B4;
    }
    #continent_points[continent="Asia"] {
      marker-fill: #B2DF8A;
    }
    #continent_points[continent="Australia"] {
      marker-fill: #33A02C;
    }
    #continent_points[continent="Europe"] {
      marker-fill: #FB9A99;
    }
    #continent_points[continent="North America"] {
      marker-fill: #E31A1C;
    }
    #continent_points[continent="Oceania"] {
      marker-fill: #FDBF6F;
    }
    #continent_points[continent="South America"] {
      marker-fill: #FF7F00;
    }

    Example 2: CartoCSS syntax structured by category

    Marker fill values are applied to the overall style of the map. marker-line-opacity, marker-placement, and marker-type are removed from the overall map style, since the default values for these properties do not render any styling effects, they are not necessary.

    Tip: In some cases, default values for CartoCSS properties render no styling effects on your map. If you apply CartoCSS syntax with the default values noneundefined, the map appears the same with or without these properties. Ensure to define values for properties that apply no default styling.

    Each point is categorized as [continent="name"] { and contains its own marker-fill style. You do not need to preface each point with the #continent_points label. Note how syntax highlighting is applied to clearly indicate the category.

    #continent_points {
      marker-fill-opacity: 0.9;
      marker-line-color: #FFF;
      marker-line-width: 1;
      marker-width: 10;
      marker-allow-overlap: true;
    
      [continent="Africa"] {
        marker-fill: #A6CEE3;
      }
      [continent="Antarctica"] {
        marker-fill: #1F78B4;
      }
      [continent="Asia"] {
        marker-fill: #B2DF8A;
      }
      [continent="Australia"] {
        marker-fill: #33A02C;
      }
      [continent="Europe"] {
        marker-fill: #FB9A99;
      }
      [continent="North America"] {
        marker-fill: #E31A1C;
      }
      [continent="Oceania"] {
        marker-fill: #FDBF6F;
      }
      [continent="South America"] {
        marker-fill: #FF7F00;
      }
    }

    Example 3: CartoCSS syntax structured by @ values

    Apply the @ symbol to lists of all the color values for your categories. The CartoCSS syntax is structured so that you can apply all your color changes in one section @name: color; and reference the point style within the category label marker-fill: @name;. This enables you to visualize exactly where your marker-fill values are located, in addition to the overall map styles.

    @africa: #A6CEE3;
    @antarctica: #1F78B4;
    @asia: #B2DF8A;
    @australia: #33A02C;
    @europe: #FB9A99;
    @northamerica: #E31A1C;
    @oceania: #FDBF6F;
    @southamerica:#FF7F00; 
    
    #continent_points {
      marker-fill-opacity: 0.9;
      marker-line-color: #FFF;
      marker-line-width: 1;
      marker-width: 10;
      marker-allow-overlap: true;
    
      [continent="Africa"] {
       marker-fill: @africa;
      }
      [continent="Antarctica"] {
        marker-fill: @antarctica;
      }
      [continent="Asia"] {
        marker-fill: @asia;
      }
      [continent="Australia"] {
        marker-fill: @australia;
      }
      [continent="Europe"] {
        marker-fill: @europe;
      }
      [continent="North America"] {
        marker-fill: @northamerica;
      }
      [continent="Oceania"] {
        marker-fill: @oceania;
      }
      [continent="South America"] {
        marker-fill: @southamerica;
      }
    }

    Example 4: Multiple Symbolizers for a Map Layer

    In some cases, you may need to apply multiple symbolizers to one map layer. For example, a point layer typically contains marker syntax. You can also attach other compatible symbolizer properties, to achieve a desired styling effect.

    Enter a double-colon symbol :: to indicate a duplicate map layer without actually adding a new layer to your map. This dummy layer created through CartoCSS styling acts as an attachment, enabling you to apply multiple symbolizers to the selected layer.

    Suppose you have a point symbol and want to put a glowing halo around it. You need CartoCSS values for the point style and CartoCSS values for the glowing halo.

    • Add the styling for the points in your map layer
    • Add a second, attachment, layer of the same data and create the styling for the halo
    /** bottom attachment of the glowing halo **/
    
    #layer {
     marker-width: 20;
     marker-fill: teal;
     marker-fill-opacity: 1;
     marker-line-color: #FFF;
     marker-line-width: 0;
     marker-line-opacity: 1;
     marker-placement: point;
     marker-type: ellipse;
     marker-allow-overlap: true;
    }
    /** top layer of the symbol**/
    
    #layer {
     marker-width: 10;
     marker-fill: #FFB927 ;
     marker-fill-opacity: 0.9;
     marker-line-color: #FFF;
     marker-line-width: 0;
     marker-line-opacity: 1;
     marker-placement: point;
     marker-type: ellipse;
     marker-allow-overlap: true;
    }

    Alternatively, you can achieve the same effect by using a single map layer and inserting the double-colon symbol :: You can type any text to describe the styling element that is being applied.

    #layer {
      
     //bottom layer of symbol
      ::halo {
        marker-width: 20;
        marker-fill: teal;
        marker-fill-opacity: 1;
        marker-line-color: #FFF;
        marker-line-width: 0;
        marker-line-opacity: 1;
        marker-placement: point;
        marker-type: ellipse;
        marker-allow-overlap: true;
      }
    
    //top layer of symbol  
       marker-width: 10;
       marker-fill: #FFB927 ;
       marker-fill-opacity: 0.9;
       marker-line-color: #FFF;
       marker-line-width: 0;
       marker-line-opacity: 1;
       marker-placement: point;
       marker-type: ellipse;
       marker-allow-overlap: true;  
    }
    • The ::halo describes the style elements that you are applying to the halo

    • The default, top layer describes the style elements that you are applying to the point

    Note: Similar to how map layers are rendered, symbolizers are rendered from bottom to top. To see an example, view this live map which is using multiple symbolizers applied to point styles.

    Adding Comments to your Code

    If you are just learning CartoCSS, it might be useful to add comments next to lines of your CartoCSS code. For example, you can add comments to describe a specific hex color, the default value for a property, the available values, and so on.

    Enter comments by using the following format in your CartoCSS code. Note the required spacing:

    cartocss-property; /* comment */

    Example of Comments in CartoCSS

    In the following example, there are user comments entered in the marker-line-color, marker-placement, marker-width, and marker-fill CartoCSS properties.

    /** simple visualization */
    
    #month_day{
      marker-fill-opacity: 0.9;
      marker-line-color: #FFF; /* white */
      marker-line-width: 1;
      marker-line-opacity: 1;
      marker-placement: point; /* options are point, line, interior */
      marker-type: ellipse;
      marker-width: 15; /* default value was 10 */
      marker-fill: #2E5387; /* hex color is St Tropaz */
      marker-allow-overlap: true;
      marker-comp-op: overlay;
    }

    As long as you are careful with the spacing, these comments will not interfere when applying CartoCSS style to your map.

    Tip: The CartoCSS Editor notifies you if there are any errors in the code.