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%;
}
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 placedstyle
contains the information about the basemapcenter
indicates the area of the world we are going to visualizezoom
defines the default zoom leveldragRotate
disables the map rotation1
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:
At this point you will have a basic map (example).
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');
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();
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);
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.