Skip to content

Use markers to call out points on the map. Marker locations are expressed in latitude/longitude coordinates, and can either appear as icons or as circles.

Data sources

Point data for markers can come from a variety of sources:

  • SpatialPoints or SpatialPointsDataFrame objects (from the sp package)
  • POINT, sfc_POINT, and sf objects (from the sf package); only X and Y dimensions will be considered
  • Two-column numeric matrices (first column is longitude, second is latitude)
  • Data frame with latitude and longitude columns. You can explicitly tell the marker function which columns contain the coordinate data (e.g. addMarkers(lng = ~Longitude, lat = ~Latitude)), or let the function look for columns named lat/latitude and lon/lng/long/longitude (case insensitive).
  • Simply provide numeric vectors as lng and lat arguments

Note that MULTIPOINT objects from sf are not supported at this time.

Icon Markers

Icon markers are added using the addMarkers() or the addAwesomeMarkers() functions. Their default appearance is a dropped pin. As with most layer functions, the popup argument can be used to add a message to be displayed on click, and the label option can be used to display a text label either on hover or statically.


# Show first 20 rows from the `quakes` dataset
leaflet(data = quakes[1:20,]) %>% addTiles() %>%
  addMarkers(~long, ~lat, popup = ~as.character(mag), label = ~as.character(mag))

Customizing Marker Icons

You can provide custom markers in one of several ways, depending on the scenario. For each of these ways, the icon can be provided as either a URL or as a file path.

For the simple case of applying a single icon to a set of markers, use makeIcon().

greenLeafIcon <- makeIcon(
  iconUrl = "",
  iconWidth = 38, iconHeight = 95,
  iconAnchorX = 22, iconAnchorY = 94,
  shadowUrl = "",
  shadowWidth = 50, shadowHeight = 64,
  shadowAnchorX = 4, shadowAnchorY = 62

leaflet(data = quakes[1:4,]) %>% addTiles() %>%
  addMarkers(~long, ~lat, icon = greenLeafIcon)

If you have several icons to apply that vary only by a couple of parameters (i.e. they share the same size and anchor points but have different URLs), use icons() icons() performs similarly to data.frame(), in that any arguments that are shorter than the number of markers will be recycled to fit.

quakes1 <- quakes[1:10,]

leafIcons <- icons(
  iconUrl = ifelse(quakes1$mag < 4.6,
  iconWidth = 38, iconHeight = 95,
  iconAnchorX = 22, iconAnchorY = 94,
  shadowUrl = "",
  shadowWidth = 50, shadowHeight = 64,
  shadowAnchorX = 4, shadowAnchorY = 62

leaflet(data = quakes1) %>% addTiles() %>%
  addMarkers(~long, ~lat, icon = leafIcons)

Finally, if you have a set of icons that vary in multiple parameters, it may be more convenient to use iconList(). It lets you create a list of (named or unnamed) makeIcon() icons, and select from that list by position or name.

# Make a list of icons. We'll index into it based on name.
oceanIcons <- iconList(
  ship = makeIcon("ferry-18.png", "ferry-18@2x.png", 18, 18),
  pirate = makeIcon("danger-24.png", "danger-24@2x.png", 24, 24)

# Some fake data
df <- sp::SpatialPointsDataFrame(
    (runif(20) - .5) * 10 - 90.620130,  # lng
    (runif(20) - .5) * 3.8 + 25.638077  # lat
  data.frame(type = factor(
    ifelse(runif(20) > 0.75, "pirate", "ship"),
    c("ship", "pirate")

leaflet(df) %>% addTiles() %>%
  # Select from oceanIcons based on df$type
  addMarkers(icon = ~oceanIcons[type])

Awesome Icons

Leaflet supports even more customizable markers using the awesome markers leaflet plugin.

The addAwesomeMarkers() function is similar to addMarkers() function but additionally allows you to specify custom colors for the markers as well as icons from the Font Awesome, Bootstrap Glyphicons, and Ion icons icon libraries.

Similar to makeIcon(), icons(), and iconList() described above, you have makeAwesomeIcon(), awesomeIcons() and awesomeIconList() functions, which enable you to add awesome icons.

# first 20 quakes
df.20 <- quakes[1:20,]

getColor <- function(quakes) {
  sapply(quakes$mag, function(mag) {
  if(mag <= 4) {
  } else if(mag <= 5) {
  } else {
  } })

icons <- awesomeIcons(
  icon = 'ios-close',
  iconColor = 'black',
  library = 'ion',
  markerColor = getColor(df.20)

leaflet(df.20) %>% addTiles() %>%
  addAwesomeMarkers(~long, ~lat, icon=icons, label=~as.character(mag))

The library argument has to be one of ‘ion’, ‘fa’, or ‘glyphicon’. The icon argument needs to be the name of any valid icon supported by the the respective library (w/o the prefix of the library name).

Marker Clusters

When there are a large number of markers on a map, you can cluster them using the Leaflet.markercluster plug-in. To enable this plug-in, you can provide a list of options to the argument clusterOptions, e.g.

leaflet(quakes) %>% addTiles() %>% addMarkers(
  clusterOptions = markerClusterOptions()

Using the freezeAtZoom argument of markerClusterOptions(), you can set the clustering to freeze as a specific zoom level. For example markerClusterOptions(freezeAtZoom = 5) will freeze the cluster at zoom level 5 regardless of the user’s actual zoom level.

Circle Markers

Circle markers are much like regular circles (see Lines and Shapes), except that their radius in onscreen pixels stays constant regardless of zoom level.

You can use their default appearance:

Or customize their color, radius, stroke, opacity, etc.

# Create a palette that maps factor levels to colors
pal <- colorFactor(c("navy", "red"), domain = c("ship", "pirate"))

leaflet(df) %>% addTiles() %>%
    radius = ~ifelse(type == "ship", 6, 10),
    color = ~pal(type),
    stroke = FALSE, fillOpacity = 0.5