How to customize the Map Viewer style

Learn how to customize the layer visualization in CARTO Map Viewer.

Customizing your map style using deck.gl declarative language

deck.gl supports a declarative system for describing layers and their props. This feature can be used to generate powerful visualizations directly from a JSON document. You can describe a visualization in abstract terms and you can view the results without needing to write JavaScript code.

This declarative system is used in deck.gl Playground and supports the layers from CARTO’s module. It is also the system used in CARTO Viewer to create and share tilesets visualizations.

The declarative language allows you to define the style and cartography of your visualization and set other general map options. Technically this language is based on JSON that gets transformed into Javascript objects and functions. Check out the official documentation on the JSON format for further technical details.

In this guide we are going to focus more on providing an overview of different options the language provides. We will also document the most common visualizations.

API reference

The declarative system creates deck.gl objects from a JSON representation. For instance, the initialViewState element in the JSON representation (declarative way) corresponds to a view state object when you are working with deck.gl in a programmatic way.

Usually the name-value pairs in the JSON representation correspond to object properties in deck.gl objects and the arrays correspond to JavaScript arrays. There are a couple of specific name-value pairs that are very useful:

• @@type. It is used to indicate the class of the object we want to create; for instance, for specifying the type of layer we want to use.

• @@function. It is used to specify a function to be executed to evaluate a data accessor; for instance, for using helpers to specify the color that we want to assign to features.

In the sections below we have included links to the deck.gl documentation.

General parameters

initialViewState

Type: object

Description: Defines the initial view state for the visualization.

Example: Visualization centered at (0, 0) coordinates, zoom level 2.

{
  ...
  "initialViewState": {
    "latitude": 0,
    "longitude": 0,
    "zoom": 2,
  },
  ...
}

views

Type: array

Description: Defines the views

Each view object has the following properties:

Example: Configuring an interactive MapView with the CARTO Positron basemap.

{
  ...  
  "views": [
    {
      "@@type": "MapView",
      "controller": true,
      "mapStyle": "@@#CARTO_BASEMAP.POSITRON"
    }
  ],
  ...
}

Layers (Basic Properties)

Type: array

Description: Layers to overlay on the map. It is an array so you can compose multiple layers and define their blending functions.

Example: Visualizing a BigQuery Tileset Layer from a public tileset (using public credentials) named cartobq.maps.osm_buildings that responds to mouse pointer picking events.

{
  ...  
  "layers": [
    {
      "@@type": "CartoBQTilerLayer",
      "data": "cartobq.maps.osm_buildings",
      "credentials": {
        "username": "public",
        "apiKey": "default_public"
      },
      "pickable": true,
      ...
    },
    ...
  ]
  ...
}

Layers (Styling Properties)

In this section we describe the styling properties for layers that can be used when working with @deck.gl/carto layers, based on the GeoJsonLayer.

Creating visualizations

If you click in any of the following examples you will be redirected to CARTO Viewer, where you can inspect what JSON is needed for configuring each visualization. In the examples below you will find additional information regarding how you can use style helper functions to create advanced visualizations.

Simple example with a point layer.	Simple example with a line layer.	Simple example with a polygon layer.

Assigning colors to bins.	Assigning colors to categories.	Assigning a continuous color ramp.

Style helpers

In common types of thematic map visualizations, a color is assigned to each feature based on a property. When working with the CARTO viewer to visualize a BQTilerLayer or a CartoSQLLayer, you can use the available helper layers:

• colorBins. Data values of each attribute are rounded down to the nearest value in the domain and are then styled with the corresponding color.

• colorCategories. Data values of each attribute listed in the domain are mapped one to one with corresponding colors in the range.

• colorContinuous. Data values of each field are interpolated linearly across values in the domain and are then styled with a blend of the corresponding color in the range.

These helper functions support the following properties:

ColorBins example

This example shows how you can create bins on a numeric feature property and assign a different color to each bin. We need to use the getFillColor data accessor and assign the following properties:

• @@function: colorBins.
• @@attr: The feature property name with numeric data type.
• @@domain: An array with the manual breaks/bins.
• colors: The CARTOColors palette to use.

{
  ...
  "layers": [
    {
      ...
      "getFillColor": {
        "@@function": "colorBins",
        "attr": "aggregated_total",
        "domain": [
          10,
          100,
          1000,
          10000,
          100000,
          1000000
        ],
        "colors": "Temps"
      },
      ...    
    }
  ]  
}

View this example with a tileset in the CARTO viewer here

ColorCategories example

This example shows how you can assign a different color to each feature depending on a string property value for that feature. We need to use the getFillColor data accessor and assign the following properties:

• @@function: colorCategories.
• @@attr: The feature property name with string data type.
• @@domain: The different values of the string property.
• colors: The CARTOColors palette to use.

{
  ...
  "layers": [
    {
      ...
      "getFillColor": {
        "@@function": "colorCategories",
        "attr": "pop_cat",
        "domain": [
          "low",
          "medium",
          "high"
        ],
        "colors": "RedOr"
      },
      ...    
    }
  ]  
}

View this example in the CARTO viewer here

ColorContinuous example

This example shows how you can assign a different color to each feature by interpolating between feature numeric property values. We need to use the getFillColor data accessor and assign the following properties:

• @@function: colorContinuous.
• @@attr: The feature property name with numeric data type.
• @@domain: The values we want to use for interpolation. The first color in the palette is assigned to the first domain value, the second color in the palette is assigned to the second domain value, and so on…
• colors: The CARTOColors palette to use.

{
  ...
  "layers": [
    {
      ...
      "getFillColor": {
        "@@function": "colorContinuous",
        "attr": "aggregated_total",
        "domain": [
          1,
          100,
          1000,
          10000,
          500000
        ],
        "colors": "Peach"
      },
      ...    
    }
  ]  
}

View this example in the CARTO viewer here

Highlighting features

It is possible to highlight features on hover using the following attributes in the layer object:

"autoHighlight": true
"pickable": true,
"highlightColor": [232,133, 113],
"uniqueIdProperty": "id",

The uniqueIdProperty is needed to specify the attribute that identifies the feature uniquely across the dataset. It is case sensitive.