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

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. In order to start creating maps, you will need text editor and an internet connection.

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. If you prefer to use the minified file, which is lighter and therefore loads faster, you can use https://libs.cartocdn.com/carto-vl/v0.10.0/carto-vl.min.js. You will also need to add Mapbox GL JavaScript and CSS files. This enables you to use both carto and mapboxgl in your code.

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/v0.10.0/carto-vl.js"></script>

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

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

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 object to initialize it using the following parameters:

  • container indicates where the map is going to be placed
  • style sets the basemap style to use
  • center sets the opening extent of the basemap
  • zoom sets the default zoom level of the basemap
  • dragRotate disables map rotation
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:

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'
});

Define 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 populated places around the world from Natural Earth.

1

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

Define 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();

Define map layer

Now that you have defined 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 defined the layer, you need to use the addTo method to add it to the map.

1

layer.addTo(map);

Set custom style to Viz object

Using the Viz object you created in a previous step, override the default by adding styling for the color and size of the points on your map:

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.

All together

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
47
48
49
50
51
52
53

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8">

    <script src="https://libs.cartocdn.com/carto-vl/v0.10.0/carto-vl.js"></script>
    <script src='https://api.tiles.mapbox.com/mapbox-gl-js/v0.50.0/mapbox-gl.js'></script>
    <link href='https://api.tiles.mapbox.com/mapbox-gl-js/v0.50.0/mapbox-gl.css' rel='stylesheet' />

    <link href="https://carto.com/developers/carto-vl/v0.10.0/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,
            dragRotate: false,
        });

        //** 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>