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 library here


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.

CARTO VL relies on Mapbox GL to render 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.

Here you will find a series of guides that are meant to lead you from the basics of creating a map to more advanced techniques for developing powerful, interactive visualizations with CARTO VL.

Below are short descriptions for each guide to help you get started:

  • Getting started: the basics of getting started with CARTO VL from setting up your .html file to adding data and visualizing it.
  • Add data sources: gain a better understanding of what data sources CARTO VL supports, how to add them to your map, and when to choose one source type or another.
  • Style with expressions: learn about the foundational pieces of styling properties in CARTO VL, the use of expressions and the visualization API.
  • Data-driven visualizations (part 1): get introduced to the ramp expression and explore its use to match inputs to values over a variety of data properties.
  • Data-driven visualizations (part 2): build upon the use of ramp and explore its use for a wider variety of map types.
  • Aggregation and data summaries: explore the use of aggregation functions to extract and visualize a variety of values from your datasets.
  • Zoom-based styles: learn how to take advantage of features for zoom-based styling for multi-scale thematic mapping.
  • Animated visualizations: learn how to make animated maps that tell a story by gaining a better understanding of animation parameters.
  • Add interactivity and events: learn how to add user interactions to make your visualization more dynamic and provide a richer experience for the end-user.
  • Add legends: explore how to enrich your visualizations with legends to aid interpretation of symbolized features.
  • Add widgets: explore how to enrich your visualizations with widgets to provide additional context from your datasets.
  • Build custom charts: learn how to display custom charts using histogram expressions and an external charting library.

If there is any word or term you do not understand while reading the guides, please take a look to our CARTO VL Glossary or, if it is not just related to CARTO VL, to our CARTO Glossary.