Thematic Maps

Thematic maps are geographical maps in which spatial data distributions are visualized. This package offers a flexible, layer-based, and easy to use approach to create thematic maps, such as choropleths and bubble maps.


version 2.2

  • improved tm_rgb
  • improved breaks in interactive maps
  • added bbox argument to qtm
  • improved projection shortcut codes (using EPSG database)
  • fixed several bugs (see github)

version 2.1-1

  • fixed two small bugs

version 2.1

  • added option max.raster (maximum raster size)
  • made rasters in view mode faster
  • bug fixed for geometry collection objects without data in view mode
  • improved handling of manual palettes
  • tmap_arrange can take a list of tmap objects

version 2.0

  • [!] tmap migrated from sp to sf. sp objects are still supported, but all internal functions are based on sf
  • [!] added tm_sf which draws sf objects
  • [!] renamed all xxx_tmap functions (e.g. save_tmap) to tmap_xxx for consistency
  • [!] added tm_basemap and tm_tiles: now, multiple (overlay) tiled maps can be shown
  • [!] rearranged tmap options, styles and formats. See tmap_options, tmap_style, tmap_format, tm_style and tm_format
  • [!] added filter argument to tm_shape and added colorNULL to layer functions
  • added tm_minimap
  • added remove.NA.facets to tm_facets
  • units data columns are supported
  • tmap_animation enhanced with loop options
  • added tmap_tips()
  • all changes are backwards compatible with 1.11-2
  • vignettes rewritten, including a vignette that describes the changes of 2.0

version 1.11-2

  • added references to JSS paper (including citation)

version 1.11-1

  • fixed bug in labels argument of tm_fill
  • fixed bug regarding legend symbols in facets with free scales
  • fixed bug in rasters in view mode
  • improved popup width in view mode

version 1.11

  • added text.align and to legend.format
  • legend.(aes).reverse added to the layer functions
  • symbol shapes can be put in a list for small multiples, and named according the values of the variable specified with the shape argument
  • grid labels can now be rotated and formatted
  • changed default values of free.coords and drop.units in tm_facets
  • fixed bug with all NA's in view mode
  • fixed bug with dismo::gmap raster shapes
  • fixed bug for ambiguous values for aesthetics (e.g. when "blue" is also a variable name)
  • NOTE: this will be the last version before the major update (in which sf fully replaces sp)

version 1.10

  • [!] tm_scale_bar, tm_text, and tm_grid now supported in view mode (required leaflet 1.1.0)
  • added along argument to tm_facets, which enables facetting along multiple pages (or animation frames)
  • added main.title argument to tm_layout
  • added tmap_options, including the new option tmap.unit ("metric" or "imperial"")
  • improved automatic labeling of breaks
  • improved legend in view mode: missing values are shown by default (like in plot mode)
  • improved bubble scaling in view mode
  • fixed bug aspect ratio bug

version 1.8-1

  • added tm_rgb (shortcut for rgb rasters)
  • fixed interactive maps in rmarkdown
  • fixed bug in qtm called without arguments

version 1.8

  • [!] package split: non-plotting functions migrated to tmaptools
  • added tmap_arrange for arranging custom small multiples
  • added simplify argument to tm_shape
  • added error message for NA-projected shapes in view mode
  • improved unit handling, which now can be set to metric or imperial
  • NA values allowed in direct color variables
  • sf (simple features) objects supported

version 1.6-1

  • improved projections: code is more efficient now and shortcuts are renewed. Also, CRS objects are now supported for all project arguments (e.g. tm_shape, set_projection), and as.CRS is added to get_projection and get_proj4.
  • Rscript works: methods is moved from imports to depends

version 1.6

  • [!] tm_symbols added, to create proportional symbol maps: besides bubbles, it also supports other symbol shapes, png icons, and small ggplot2 plots
  • [!] imported cartogram function from cartogram package (tnx Sebastian!)
  • [!] reverse geocoding function rev_geocode_OSM added
  • [!] tm_logo added
  • added popup.vars to base layer functions
  • bounding box (argument bbox in tm_shape) working in view mode
  • geocode_OSM improved: a SpatialPointsDataFrame can now be returned
  • last_map added, which retrieves the last produced map
  • crop_shape can also handle polygons as cropping area
  • append_data improved; the under and over coverage information can be retrieved with under_coverage and over_coverage
  • interpolate parameter added to tm_rasters
  • added support for custom legend formating functions
  • legend items can now be stacked horizontally
  • legend width and height can be determined fully manually (with negative values for legend.height and legend.width)
  • argument interval.closure added to layer functions to determine where intervals are closed
  • added warnings for non-supported elements in view mode
  • fixed raster brick bug
  • fixed save_tmap/get_asp_ratio bug

version 1.4-1

  • add just argument as anchor for text labels, legend and attributes position
  • map attributes (such as scale bar) can be placed outside the frame
  • added tm_xlab and tm_ylab
  • RGB raster support, see tm_raster
  • static text (i.e titles, credits, legend titles, labels) support expressions
  • updated Europe shape: projection and boundig box are now consistent with Eurostat publications
  • added crop_shape, a convenient wrapper around raster::crop

version 1.4

  • [!] interactive mapping added. Now, tmap has two modes: "plot" (graphics device) and "view" (interactive viewer, which is a leaflet widget)
  • [!] facets (small multiples) improved: group by two variables possible, panel layout added, missing data can be shown separately
  • added geocode_OSM, a function to find coordinates
  • improved set_projection for raster objects
  • added double_line and offset_line
  • added insets option in save_tmap
  • improved default settings for contrast arugment regarding seq and div palettes
  • improved automatic positions of legend and map attributes (more specifically, legend snaps to righthand-side without need to adjust legend.width, and legend and attributes position improved when double frame is enabled)
  • improved tm_layouts's design.mode output
  • lwd parameter added to tm_scale_bar and tm_compass
  • fixed bb bug

version 1.2-1

  • fixed bug with PROJ.4 version < 4.9.1
  • improved error messages
  • rd projection reset to +init=epsg:28992, since the latter now has a +towgs item
  • fixed bug of print.tmap returned object

version 1.2

  • added read_osm, a function to read Open Street Map data
  • added bb, a handy bounding box function
  • added layout themes with tm_style and tm_format
  • added automatic text labeling
  • added interactive SVG, that can be opend in RStudio (see itmap)
  • added map compass (tm_compass)
  • added text aesthetics size and col
  • added automatic map coloring
  • added earth boundary, which is useful for projected world maps
  • added warped grid lines (e.g. long-lat lines can be shown in projected maps)
  • added new color scale modes (enabled with style="cat", "cont", and "order")
  • added save_tmap
  • added smooth_map, smooth_raster_cover, sample_dots, points_to_raster and poly_to_raster
  • added read_GPX
  • improved automatic layout regarding title, legend, and map attributes
  • layer arguments, e.g. palette, can take multiple values for small multiples
  • improved grid lines (labels can also be placed outside frame)
  • arguments free.coords and drop.shapes of tm_facets working
  • updated examples and vignette
  • fixed viewport bug
  • see ?tmap for a structured overview of all tmap functions

version 1.0

  • added tm_credits and tm_scale_bar
  • added is.master argument to tm_shape, that determines which shape is the master
  • added unit and unit.size arguments to tm_shape that correlates the coordinates with the desired units
  • added tm_polygons, which is a combination of tm_fill and tm_borders
  • fixed several small bugs

version 0.8

  • added tm_raster
  • improved legend behaviour: legend titles should be set in the layer functions (instead of in tm_layout)
  • removed crop_shape, since raster::crop does the same job, but, but faster
  • out-of-scope functions migrated to spatialToolbox package, available on

version 0.7.1

  • fixed big in scale parameter (global scale set in tm_layout)

version 0.7

  • enhanced small multiples (tm_facets) with respect to scaling and free coordinate scales
  • added alpha argument to tm layers for transparency
  • added text shadow argument
  • added function split to split a shape object and sbind to combine shape objects.
  • added automatic legend positioning when legend.position=NULL
  • improved number formatting in legend
  • improved inner.margins and outer.margins. Both can take one value (e.g. outer.margins=0 rather than outer.margins=c(0,0,0,0))
  • improved qtm: tm_facets parameters working, and also fixed scale parameter bug
  • improved all examples for approx_areas, calc_densities
  • fixed bug regarding drawing a frame with outer.margins=0.
  • fixed bug in plotting blubbles
  • improved temp file handling in animation_tmap
  • added functions to get and set polygon directions, and to calculate the intersection ratios of polygons (intersection_shapes)

version 0.6

  • this is the the first CRAN version
  • a newer version may be available on
  • to get started, see the package vignette 'tmap in a nutshell' and the help files
  • if you have any questions or suggestions, please contact me (mtennekes at gmail dot com)

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


3.2 by Martijn Tennekes, a month ago

Report a bug at

Browse source code at

Authors: Martijn Tennekes [aut, cre] , Jakub Nowosad [ctb] , Joel Gombin [ctb] , Sebastian Jeworutzki [ctb] , Kent Russell [ctb] , Richard Zijdeman [ctb] , John Clouse [ctb] , Robin Lovelace [ctb] , Jannes Muenchow [ctb]

Documentation:   PDF Manual  

Task views: Official Statistics & Survey Methodology, Analysis of Spatial Data

GPL-3 license

Imports tmaptools, sf, stars, units, grid, RColorBrewer, viridisLite, classInt, htmltools, htmlwidgets, widgetframe, leaflet, leafsync, leafem, stats, rlang, utils

Depends on methods

Suggests rmapshaper, rmarkdown, knitr, png, cartogram, osmdata, ggplot2, dplyr, tidyr, shiny, testthat, covr, av, gifski

Imported by GapAnalysis, edbuildmapr, ppcSpatial, spatialrisk.

Depended on by RGISTools.

Suggested by OpenLand, SpatialKDE, csodata, eSDM, pct, sf, spatialfusion, spatialreg, spdep, stats19, stplanr, tmaptools, waterquality.

See at CRAN