CARTO for deck.gl

Style 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 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 a guide to the different options the language provides and document 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.

1
2
3
4
5
6
7
8
9

{
  ...
  "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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  ...  
  "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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  ...  
  "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 is the JSON needed for configuring each visualization. Below the examples you will find additional information regarding how you can use the style helper functions to create advanced visualizations.

Simple Point

Simple example with a point layer.

Simple Line

Simple example with a line layer.

Simple Polygon

Simple example with a polygon layer.

Color Bins

Assigning colors to bins.

Color Categories

Assigning colors to categories.

Color Continuous

Assigning a continuous color ramp.

Style helpers

A common type of map visualization is assigning a color 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  ...
  "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 feature property value. 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  ...
  "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 a numeric feature property value. 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 interpolating. 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
  ...
  "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:

1
2
3
4

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