How to customize the Map Viewer style

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

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: Indicates the class of the object you want to create; for instance, for specifying the type of layer.
• @@function: Specifies a function to be executed to evaluate a data accessor; for instance, for using helpers to specify the color assigned to features.

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 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)

Styling properties for layers based on the GeoJsonLayer:

Creating visualizations

Style helpers

In common types of thematic map visualizations, a color is assigned to each feature based on a property. You can use the available helper functions:

• colorBins: Data values are rounded down to the nearest value in the domain and styled with the corresponding color.
• colorCategories: Data values listed in the domain are mapped one to one with corresponding colors in the range.
• colorContinuous: Data values are interpolated linearly across values in the domain and styled with a blend of the corresponding color.

These helper functions support the following properties:

ColorBins example

Create bins on a numeric feature property and assign a different color to each bin:

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

ColorCategories example

Assign a different color to each feature depending on a string property value:

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

ColorContinuous example

Assign a different color to each feature by interpolating between numeric property values:

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

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.