Skip to contents

Draw a thematic map quickly. This function is a convenient wrapper of the main plotting method of stacking tmap-elements. Without arguments or with a search term, this functions draws an interactive map.


  fill = tm_const(),
  col = tm_const(),
  size = tm_const(),
  shape = tm_const(),
  lwd = tm_const(),
  lty = tm_const(),
  fill_alpha = tm_const(),
  col_alpha = tm_const(),
  by = NULL,
  scale = NULL,
  title = NULL,
  crs = NULL,
  bbox = NULL,
  basemaps = NULL,
  overlays = NULL,
  zindex = NA,
  group = NA,
  group.control = "check",
  style = NULL,
  format = NULL,



One of:

  • shape object, which is an object from a class defined by the sf or stars package. Objects from the packages sp and raster are also supported, but discouraged.

  • Not specified, i.e. qtm() is executed. In this case a plain interactive map is shown.

  • An OpenStreetMap search string, e.g. qtm("Amsterdam"). In this case a plain interactive map is shown positioned according to the results of the search query (from OpenStreetMap nominatim)

fill, col, size, shape, lwd, lty, fill_alpha, col_alpha

Visual variables.


data variable name by which the data is split, or a vector of two variable names to split the data by two variables (where the first is used for the rows and the second for the columns). See also tm_facets().


numeric value that serves as the global scale parameter. All font sizes, symbol sizes, border widths, and line widths are controlled by this value. The parameters symbols.size, text.size, and lines.lwd can be scaled separately with respectively symbols.scale, text.scale, and lines.scale. See also ....


main title. For legend titles, use, where X is the layer name (see ...).


Either a crs object or a character value (PROJ.4 character string). By default, the projection is used that is defined in the shp object itself.


bounding box. Argument passed on to tm_shape()


name(s) of the provider or an URL of a tiled basemap. It is a shortcut to tm_basemap(). Set to NULL to disable basemaps. By default, it is set to the tmap option basemaps.


name(s) of the provider or an URL of a tiled overlay map. It is a shortcut to tm_tiles().








Layout options (see tm_layout()) that define the style. See tmap_style() for details.


Layout options (see tm_layout()) that define the format. See tmap_format() for details.


arguments passed on to the tm_* functions. The prefix of these arguments should be with the layer function name without "tm_" and a period. For instance, the palette for polygon fill color is called fill.palette. The following prefixes are supported: shape., fill., borders., polygons., symbols., dots., lines., raster., text., layout., grid., facets., and view.. Arguments that have a unique name, i.e. that does not exist in any other layer function, e.g. convert2density, can also be called without prefix.


A tmap-element


The first argument is a shape object (normally specified by tm_shape()). The next arguments, from fill to raster, are the aesthetics from the main layers. The remaining arguments are related to the map layout. Any argument from any main layer function, such as tm_polygons(), can be specified (see ...). It is also possible to stack tmap-elements on a qtm plot. See examples.

By default, a scale bar is shown. This option can be set with tmap_options() (argument qtm.scalebar). A minimap is shown by default when qtm is called without arguments of with a search term. This option can be set with tmap_options() (argument qtm.minimap).


Tennekes, M., 2018, tmap: Thematic Maps in R, Journal of Statistical Software, 84(6), 1-39, doi:10.18637/jss.v084.i06


data(World, rivers, metro)

# just the map

# choropleth
qtm(World, fill = "economy", format = "World", style = "col_blind", projection = "+proj=eck4")

# choropleth with more specifications
qtm(World, fill="HPI", fill.n = 9, fill.palette = "div",
    fill.title = "Happy Planet Index", = "name", 
    style = "gray", format = "World", projection = "+proj=eck4")

# this map can also be created with the main plotting method,
# which is recommended in this case.
if (FALSE) {
tm_shape(World, projection = "+proj=eck4") +
    tm_polygons("HPI", n = 9, palette = "div",
        title = "Happy Planet Index", id = "name") +
tm_style("gray") +

# bubble map
if (FALSE) {
qtm(World, borders = NULL) + 
qtm(metro, symbols.size = "pop2010", 
    symbols.title.size= "Metropolitan Areas", "name",
    format = "World")

# dot map
if (FALSE) {
current.mode <- tmap_mode("view")
qtm(metro, bbox = "China")
tmap_mode(current.mode) # restore mode

if (FALSE) {
# without arguments, a plain interactive map is shown (the mode is set to view)

# search query for OpenStreetMap nominatim