CARTO VL

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

In this guide, you will learn the basics of visualizing data with CARTO VL on top of a world basemap. There are no previous requirements to complete this guide, but a basic knowledge of HTML, CSS and JavaScript would be helpful.

After completing this guide, you will have your first CARTO VL map!

Basic setup

The most straight-forward way to use CARTO VL is to include the required files from our CDN as seen in the code below. You will also need to add Mapbox GL JavaScript and CSS files.

1
2
3
4
5
6
7
8

<head>
  <!-- Include CARTO VL JS from the CARTO CDN-->
  <script src="https://libs.cartocdn.com/carto-vl/v1.3.1/carto-vl.min.js"></script>

  <!-- Include Mapbox GL from the Mapbox CDN-->
  <script src="https://api.tiles.mapbox.com/mapbox-gl-js/v1.0.0/mapbox-gl.js"></script>
  <link href="https://api.tiles.mapbox.com/mapbox-gl-js/v1.0.0/mapbox-gl.css" rel="stylesheet" />
</head>

Note: Mapbox GL: CARTO VL is not compatible with every version. We recommend using the same version that we use in the examples. However, every version from v0.50.0 should work. Historically, we provided patched MGL bundles, but this is no longer required.

Note: Developers: if you have experience with npm and a build system in your project (webpack, rollup…), you can install CARTO VL library with npm install @carto/carto-vl. You can import it with import carto from '@carto/carto-vl' and then you will have access to an already babelified version of the library, ready to be used.

Add map container

Next, you need to create a div where the map will be drawn:

1

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

Style the map div to ensure the map displays properly:

1
2
3
4
5

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

Add basemap and set properties

Once you have a div for your map, you have to use the mapboxgl.Map constructor to create a new map with the following parameters:

  • container: element ID to indicate where the map is going to be placed
  • style: sets the basemap style to use
  • center: sets the opening center coordinates of the map (longitude, latitude)
  • zoom: sets the default zoom level of the map
1
2
3
4
5
6

const map = new mapboxgl.Map({
      container: 'map',
      style: carto.basemaps.voyager,
      center: [0, 30],
      zoom: 2
    });

For the basemap style parameter, you can add either Mapbox custom styles or one of the three predefined styles offered by CARTO:

At this point you will have a basic map with Voyager as the base, that opens at zoom level 2 and centered on the world:

View this step here

Define user

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 username and apiKey. For guides and examples, we provide a public CARTO account that you can use to try out the library:

1
2
3
4

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

Create source

The next step is to define the source from your account to be displayed on the map. In the example below, the source is a dataset named populated_places with all the most populated places around the world from Natural Earth.

1

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

Create Viz object

A Viz object is one of the core elements of CARTO VL. It defines how the data will be styled and displayed on your map.

Create an empty Viz object that uses the default CARTO VL styling:

1

const viz = new carto.Viz();

Create map layer

Now that you have created a source and a Viz object, you need to create a new layer that can be added to the map.

1

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

Add map layer

Once you have created the layer, you need to use the addTo method to add it to the map.

1

layer.addTo(map);

Defining a custom style for the Viz object

Instead of using the Viz object you created in a previous step, with the default values, we can set custom values for the color and size of the points on your map:

1
2
3
4

const viz = new carto.Viz(`
    color: purple
    width: 5
`);

For more information about styling, check out the guide Style with Expressions.

All together

You can explore the final step here

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <script src="https://libs.cartocdn.com/carto-vl/v1.3.1/carto-vl.min.js"></script>
    <script src="https://api.tiles.mapbox.com/mapbox-gl-js/v1.0.0/mapbox-gl.js"></script>
    <link href="https://api.tiles.mapbox.com/mapbox-gl-js/v1.0.0/mapbox-gl.css" rel="stylesheet" />
    <link href="https://carto.com/developers/carto-vl/v1.3.1/examples/maps/style.css" rel="stylesheet">
</head>
<body>
    <!-- Add map container -->
    <div id="map"></div>
    <script>
        // Add basemap and set properties
        const map = new mapboxgl.Map({
            container: 'map',
            style: carto.basemaps.voyager,
            center: [0, 30],
            zoom: 2
        });

        //** CARTO VL functionality begins here **//

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

        // Define source
        const source = new carto.source.Dataset('populated_places');

        // Define Viz object and custom style
        const viz = new carto.Viz(`
            color: purple
            width: 5
        `);

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

        // Add map layer
        layer.addTo(map);
    </script>
</body>
</html>