Skip to contents

Map layer: basemap / overlay tiles

Source: R/tm_layers_aux.R
tm_basemap.Rd

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

if (FALSE) { # \dontrun{
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)
}
} # }