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!
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.
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.
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
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%;
}
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 placedstyle
contains the information about the basemapcenter
indicates the area of the world that is going to be visualizedzoom
defines the default zoom leveldragRotate
disables the map rotation1
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:
carto.basemaps.voyager
https://basemaps.cartocdn.com/gl/voyager-gl-style/style.jsoncarto.basemaps.positron
https://basemaps.cartocdn.com/gl/positron-gl-style/style.jsoncarto.basemaps.darkmatter
https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.jsonAt this point you will have a basic map:
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'
});
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');
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();
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);
Once you have the layer, you need to use the addTo
method to add it to the map.
1
layer.addTo(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 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.
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>