
CARTO for deck.gl
Build applications using CARTO & deck.gl advanced framework for data visualization
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.
Property Name | Type | Description |
---|---|---|
latitude | number | Latitude at the map center. |
longitude | number | Longitude at the map center. |
zoom | number | Initial zoom level. |
pitch | number | Default: 0. Pitch angle (in degrees). |
bearing | number | Default: 0. Bearing angle (in degrees). |
minZoom | number | Default: 0. Min zoom level. |
maxZoom | number | Default: 20. Max zoom level. |
minPitch | number | Default: 0. Min pitch angle. |
maxPitch | number | Default: 60. Max pitch angle. |
Example: Visualization centered at (0, 0) coordinates, zoom level 2.
|
|
views
Type: array
Description: Defines the views
Each view object has the following properties:
Property Name | Type | Description |
---|---|---|
@@type | string | Use MapView in the CARTO viewer for a Web Mercator Projection. Other types of views are also supported by the declarative syntax (but not in CARTO viewer) like FirstPersonView , Globeview , OrtographicView or OrbitView . |
controller | boolean | Indicates if the map is interactive (supports pan, zoom…) or not. |
mapStyle | number | Basemap to use in the map. It can be a full URL to a vector style like this one, or it can be a string from this dictionary |
Example: Configuring an interactive MapView
with the CARTO Positron basemap.
|
|
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.
Property Name | Type | Description |
---|---|---|
@@type | string | “CartoBQTilerLayer” or “CartoSQLLayer” |
data | string | In the case of a BigQuery TileSet you indicate the project.dataset.table_name. In the case of CartoSQLLayer you indicate the SQL from CARTO to use. |
credentials | object | CARTO authentication credentials |
credentials.username | object | CARTO username |
credentials.apiKey | object | CARTO API Key. In the case of a private map you add here the api key, for a public map you can use default_public. |
credentials.region | object | Default: us . Region wher the user database is located; possible values are us or eu . Only need to be specified if you’ve specifically requested an account in the eu region. |
credentials.mapsUrl | object | Default: https://{user}.carto.com/api/v1/map . If you’re an on-premise user or you’re running CARTO from Google’s marketplace, you need to set the URL to point to your instance. |
credentials.sqlUrl | object | Default: https://{user}.carto.com/api/v2/sql . If you’re an on-premise user or you’re running CARTO from Google’s marketplace, you need to set the URL to point to your instance. |
pickable | boolean | Default: false. Indicates whether the layer responds to mouse pointer picking events. |
uniqueIdProperty | string | Default: cartodb_id . Needed for highlighting a feature split across two or more tiles if no feature id is provided. An string pointing to a tile attribute containing a unique identifier for features across tiles. |
visible | boolean | Default: true. Indicates whether the layer is visible. Under most circumstances, using visible prop to control the visibility of layers is recommended over doing conditional rendering. |
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 (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
.
Property Name | Type | Description |
---|---|---|
autoHighlight | boolean | Default: false. When true, current object pointed by mouse pointer (when hovered over) is highlighted with highlightColor. Requires pickable to be true. |
elevationScale | number | Default: 1. Elevation multiplier. The final elevation is calculated by elevationScale * getElevation(d). elevationScale is a handy property to scale all polygon elevation without updating the data. |
extruded | boolean | Default: false. Whether to extrude the polygons (based on the elevations provided by the getElevation accessor. If set to false, all polygons will be flat, this generates less geometry and is faster than simply returning 0 from getElevation. |
filled | boolean | Default: true. Whether to draw filled polygons (solid fill). Note that for each polygon, only the area between the outer polygon and any holes will be filled. This prop is effective only when the polygon is NOT extruded. |
getElevation | number or @@function | The elevation to extrude each polygon with. If a cartographic projection mode is used, height will be interpreted as meters, otherwise will be in unit coordinates. Only applies if extruded: true. If a number is provided, it is used as the elevation for all polygons. If a function is provided, it is called on each polygon to retrieve its elevation. Note: If 3D positions are returned by getPolygon, the extrusion returned by getElevation is added to the base altitude of each vertex. |
getFillColor | array or @@function | The color, in RGBA array format, to use as the fill color. If a function is provided, it is called on each object to retrieve its color. Check the color ramps section for examples. |
getLineColor | array or @@function | The color, in RGBA array format, to use as the outline color. If a function is provided, it is called on each object to retrieve its color. Check the color ramps section for examples. |
getRadius | number or @@function | The radius of each object, in units specified by radiusUnits (default meters). If a function is provided, it is called on each object to retrieve its radius. |
getLineWidth | number or @@function | The width of the outline of each object, in units specified by lineWidthUnits (default meters). If a function is provided, it is called on each object to retrieve its outline width. |
highlightColor | array or @@function | Default: [0, 0, 128, 128]. RGBA color to blend with the highlighted object (either the hovered over object if autoHighlight : true, or the object at the index specified by highlightedObjectIndex ). When the value is a 3 component (RGB) array, a default alpha of 255 is applied. If an array is supplied, it is used for the object that is currently highlighted. If a function is supplied, it is called with a pickingInfo object when the hovered object changes. The return value is used as the highlight color for the picked object. Only works with autoHighlight : true. |
lineJointRounded | boolean | Default: false. Type of joint. If true, draw round joints. Otherwise draw miter joints. |
lineWidthMinPixels | number | Default: 0. The minimum line width in pixels. |
lineWidthScale | number | Default: 1. The line width multiplier applied to all outlines of Polygon and MultiPolygon features if the stroked attribute is true. |
opacity | number | Default: 1. The opacity of the layer. |
pointRadiusMinPixels | number | The minimum radius in pixels. |
stroked | boolean | Default: true. Indicates whether to draw an outline around the polygon (solid fill). Note that both the outer polygon as well the outlines of any holes will be drawn. |
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.
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:
Property Name | Type | Description |
---|---|---|
attr | string | Attribute or column to symbolize by. |
domain | array | For colorBins defines the manual class break values. For colorCategories defines the category list (must be valid). For colorContinuous defines the attribute domain to define the data range. |
colors | string or array | Default: PurpOr. Color assigned to each domain value. If a string is provided, it must be a valid named CARTOColors palette. If an array is provided, it must be an array of colors in RGBA [ [r, g, b, [a]] ]. |
nullColor | array | Default: [204, 204, 204]. Color for null values. |
othersColor | array | Default: [119, 119, 119]. Only available for the ColorCategories helper. Fallback color for a category not assigned. |
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.
|
|
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.
|
|
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.
|
|
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:
|
|
The uniqueIdProperty
is needed to specify the attribute that identifies the feature uniquely across the dataset. It is case sensitive.