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

Introduction

Welcome to the CARTO VL guides! This documentation is meant to lead you from the basics of creating a map to advanced techniques for developing powerful interactive visualizations. After reading this guide, you will be able to create your first CARTO VL map!

Previous requirements

You will learn how to visualize information with CARTO VL by displaying a dataset on the top of a world basemap. If there is any word or term you do not understand while reading the guides, please take a look to our Glossary.

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.

What is CARTO VL?

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.

It relies on Mapbox GL to render the basemaps. Mapbox GL 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 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.

Basic setup

1
2
3
4
5
6
7
8

<head>
  <!-- Include CARTO VL JS -->
  <script src="https://libs.cartocdn.com/carto-vl/v0.9.1/carto-vl.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>

The easiest way to use CARTO VL is to include the required files from our CDN as you see in the example above: https://libs.cartocdn.com/carto-vl/v0.9.1/carto-vl.js. 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.9.1/carto-vl.min.js.

Then, you will need to add Mapbox GL JavaScript and CSS files. This will let you use both carto and mapboxgl in your code.

Currently, not every Mapbox GL version is compatible with CARTO VL. We highly recommend the following combination. If you are importing CARTO VL from npm, you have to use our Mapbox GL fork. Read more about how to do this in the advanced guide

Add map container

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%;
}

Add basemap and set properties

Once you have the div, you have use the mapboxgl object to initialize your 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 that is going to be visualized
  • 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: carto.basemaps.voyager,
      center: [0, 30],
      zoom: 2,

    });

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

At this point you will have a basic map:

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.

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, displayed, and processed. In this case you have to create an empty Viz object, that will use the style set by default.

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

1

layer.addTo(map);

Define Viz object and custom style

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 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
54
55
56
57
58
59
60

<!DOCTYPE html>
<html>

<head>
    <!-- Include CARTO VL JS -->
    <script src="https://libs.cartocdn.com/carto-vl/v0.9.1/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" />
    <!-- Make the map visible -->
    <style>
        #map {
            position: absolute;
            height: 100%;
            width: 100%;
        }
    </style>
</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: red
            width: 10
        `);

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

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

</html>