tm_basemap: Map layer: basemap / overlay tiles

In tmap: Thematic Maps

Map layer: basemap / overlay tiles

Description

Map layer that draws tiles from a tile server. tm_basemap() draws the tile layer as basemap, i.e. as bottom layer. In contrast, tm_tiles() draws the tile layer as overlay layer, where the stacking order corresponds with the order in which this layer is called, just like other map layers.

Usage

tm_basemap(
  server = NA,
  alpha = NULL,
  zoom = NULL,
  api = NULL,
  max.native.zoom = 17,
  sub = "abc",
  zindex = 0,
  group = NA,
  group.control = "radio"
)

tm_tiles(
  server = NA,
  alpha = NULL,
  zoom = NULL,
  max.native.zoom = 17,
  sub = "abc",
  zindex = NA,
  group = NA,
  group.control = "check"
)

Arguments

server	Name of the provider or an URL. Or a vector of multiple values. The list of available providers can be obtained with providers (tip: in RStudio, type ⁠leaflet::providers$⁠ to see the options). See https://leaflet-extras.github.io/leaflet-providers/preview/ for a preview of those. When a URL is provided, it should be in template format, e.g. "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png". Use NULL in tm_basemap() to disable basemaps. It can be a named vector. In that case these names will be used a group names, as alternative to the argument group.
alpha	Transparency level
zoom	Zoom level (only used in plot mode)
api	API key. Needed for Stadia and Thunderforest maps in plot mode, and for Esri/MapTiler basemaps in "maplibre"/"mapbox" mode (alternatively set the env var ARCGIS_API_KEY / MAPTILER_API_KEY). See details
max.native.zoom	Maximum native zoom level (only used in view mode). The minimum and maximum zoom levels are determined in tm_view().
sub	subdomain of the tile server. Only used when server is a url template. The default is "abc" which works for most tile servers.
zindex	Controls the stacking order of map layers. Should be set to a value above 400. By default, layers are stacked in call order, starting at 401. See details.
group	Name of the group to which this layer belongs. This is only relevant in view mode, where layer groups can be switched (see group.control)
group.control	In view mode, the group control determines how layer groups can be switched on and off. Options: "radio" for radio buttons (meaning only one group can be shown), "check" for check boxes (so multiple groups can be shown), and "none" for no control (the group cannot be (de)selected).

Details

API keys. For Stadia and Thunderforest maps, an API key is required. This can be set via the argument api. Alternatively they can be stored in environment variables "STADIA_MAPS" and THUNDERFOREST_MAPS with Sys.setenv

In view mode, each layer is rendered in a Leaflet pane named "tmap{zindex}" (e.g., "tmap401", "tmap402"), with base tile layers placed in the standard "tile" pane.

See Also

Basemaps, Modes

Examples

## Not run: 
if (requireNamespace("maptiles")) {
	# view mode
	current_mode = tmap_mode("view")
	tm_basemap("Stadia.StamenWatercolor") +
		tm_shape(World) +
		tm_polygons(
		  "HPI",
		  fill.scale = tm_scale(values = "reds"),
		  fill_alpha.scale = 0.5)

	tm_shape(World, crs = "+proj=eqearth") +
		tm_polygons(
			"HPI",
			fill.scale = tm_scale(values = "reds"),
			fill_alpha.scale = 0.5) +
	tm_basemap(NULL)

	# plot mode:
	tmap_mode("plot")
	tm_basemap() +
		tm_shape(World) +
		tm_polygons("HPI")

	tm_basemap("OpenTopoMap") +
		tm_shape(World) +
		tm_polygons(fill = NA, col = "black")

	tm_basemap("CartoDB.PositronNoLabels") +
	tm_shape(NLD_prov, crs = 4236) +
		tm_borders() +
		tm_facets_wrap("name") +
		tm_tiles("CartoDB.PositronOnlyLabels")

	# restore mode
	tmap_mode(current_mode)
}

## End(Not run)

tmap documentation built on June 26, 2026, 5:08 p.m.