Hey! This content applies only to previous CARTO products

Please check if it's relevant to your use case. On October 2021 we released a new version of our platform.
You can learn more and read the latest documentation at docs.carto.com

Questions  /  Building Maps  /  Intro to Maps

How can I customize the basemap?

Introduction to basemaps in CARTO.

Why do I need this?

  • :world_map: You want to learn about basemaps in CARTO.
  • :capital_abcd: You want to customize labels.
  • :wrench: You want to use your own basemap.

What is a basemap?

Basemaps are image tiles that are used to render the graphical representation of your map background. Basemaps include the natural and cultural features of the world; such as water bodies, topography, park areas, terrains, roads, streets, and sometimes buildings. They also display text labels of cities, countries and other geographical and physical features.

Managing labels

CARTO basemaps (Voyager, Positron, and Dark Matter) present three different options depending on your label preferences:

  • Default or labels on top.
  • Labels below.
  • Lite or no labels.


In Builder, you can select any of these three types from the basemap carrousel.

Builder Basemaps Labels


As explained in this getting started Developers guide, you can add labels on top of your data layer using a code like this one:

// Adding Voyager Basemap
L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_nolabels/{z}/{x}/{y}.png', {
  maxZoom: 18

// Adding Voyager Labels
L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_only_labels/{z}/{x}/{y}.png', {
  maxZoom: 18,
  zIndex: 10

L.tileLayer creates a layer for the basemap and the zIndex property defines the basemap labels (that sit on top of the other layers).

Using your own basemap

In Builder and CARTO.js web applications, you can import an external basemap from Mapbox projects, WMS/WMTS, TileJSON, and NASA imagery. You can also apply a solid background color as the basemap, or even import a custom tileset using an XYZ URL (such as a .png, .jpg, or .gif image URL to display a repeating pattern as your basemap).

Tip: Builder users can also use their data layers as custom basemaps, and add their own labels using CartoCSS text properties in combination with zoom-based sytling as done in this tutorial.

What’s next

:white_check_mark: Read this article to learn about basemaps for rendering map backgrounds.

:white_check_mark: Read this article to learn about inserting external basemaps in Builder.

:white_check_mark: Check this external resource to preview a wide variety of Leaflet basemap providers.