CARTO VL

This is a DEPRECATED VERSION of CARTO VL. You can find more information about the support and the availability of the different CARTO VL versions.

CARTO VL is a JavaScript library to create custom Location Intelligence applications over vector rendering.

This library is still under support but it will not be further developed. We don’t recommend starting new projects with it as it will eventually become deprecated. Instead, learn more about our current CARTO for deck.gl library here

Getting started

Basic structure

CARTO VL is a JavaScript library to create custom location intelligence applications that leverage the power of CARTO. It uses WebGL to enable powerful vector maps.

The easiest way to use CARTO VL is to include the required files from our CDN. This will add the carto and the mapboxgl objects to the global namespace.

Usage of Mapbox GL is required to render the basemaps and can be used for other functionality too, read Mapbox GL documentation for more information. However, keep in mind that CARTO VL layers can only be controlled with the CARTO VL API (this documentation) and that Mapbox GL native layers can only be controlled with the Mapbox GL API. Therefore, CARTO VL expressions cannot be used for Mapbox GL layers and vice versa.

Not every Mapbox GL version is compatible with CARTO VL. We highly recommend the following combination.

1
2
3
4
5
6
7
8

<head>
  <!-- Include CARTO VL JS -->
  <script src="https://libs.cartocdn.com/carto-vl/v0.8.0/carto-vl.min.js"></script>
  <!-- Include Mapbox GL JS -->
  <script src="https://libs.cartocdn.com/mapbox-gl/v0.48.0-carto1/mapbox-gl.js"></script>
  <!-- Include Mapbox GL CSS -->
  <link href="https://libs.cartocdn.com/mapbox-gl/v0.48.0-carto1/mapbox-gl.css" rel="stylesheet" />
</head>

Create a div where the map is going to be drawn.

1

  <div id="map"></div>

Style the div to ensure it will be displayed correctly.

1
2
3
4
5

#map {
    position: absolute;
    height: 100%;
    width: 100%;
}

Defining the basemap

Once we have the div, we use the mapboxgl object to initialize our map using the following parameters:

  • container indicates where the map is going to be placed
  • style contains the information about the basemap
  • center indicates the area of the world we are going to visualize
  • zoom defines the default zoom level
  • dragRotate disables the map rotation
1
2
3
4
5
6
7

const map = new mapboxgl.Map({
      container: 'map',
      style: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json',
      center: [0, 30],
      zoom: 2,
      dragRotate: false
    });

For basemaps you can add Mapbox custom styles or choose one of the three predefined styles offered by CARTO:

  • Voyager: https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json
  • Positron: https://basemaps.cartocdn.com/gl/positron-gl-style/style.json
  • Dark Matter: https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json

At this point you will have a basic map (example).

Defining the source

In order to render data from CARTO you need to create a CARTO account and then get the necessary credentials.

The first thing you need to do is authenticate the client with your user and apiKey.

1
2
3
4

carto.setDefaultAuth({
    user: 'cartovl',
    apiKey: 'default_public'
});

The next step is to define the source from your account to be displayed on the map. In the example below we are defining the source for a dataset named ne_10m_populated_places_simple with all the populated places around the world.

1

const source = new carto.source.Dataset('ne_10m_populated_places_simple');

Defining the Viz object

A Viz object is one of the core elements of CARTO VL and defines how the data will be styled, displayed, and processed. In this case we create an empty Viz object with the default style.

1

const viz = new carto.Viz();

Defining the layer

Now that we have defined our source and a Viz object, we need to define a layer that can be added to the map.

1

const layer = new carto.Layer('layer', source, viz);

Once we have the layer we need to use the addTo method to add it to the map. See example.

1

layer.addTo(map);

Styling the map

Using the Viz object you can decide how to visualize your data.

The following Viz object changes the color and size of the points on our map. See example.

1
2
3
4

const viz = new carto.Viz(`
    color: red
    width: 10
`);

For more information about styling, check out the guide Introduction to Styling.