Add a color legend to a map — addLegend • leaflet

When a color palette function is used in a map (e.g., colorNumeric()), a color legend can be automatically derived from the palette function. You can also manually specify the colors and labels for the legend.

Usage

addLegend(
  map,
  position = c("topright", "bottomright", "bottomleft", "topleft"),
  pal,
  values,
  na.label = "NA",
  bins = 7,
  colors,
  opacity = 0.5,
  labels = NULL,
  labFormat = labelFormat(),
  title = NULL,
  className = "info legend",
  layerId = NULL,
  group = NULL,
  data = getMapData(map)
)

labelFormat(
  prefix = "",
  suffix = "",
  between = " &ndash; ",
  digits = 3,
  big.mark = ",",
  transform = identity
)

Arguments

map: a map widget object created from leaflet()
position: the position of the legend
pal: the color palette function, generated from colorNumeric(), colorBin(), colorQuantile(), or colorFactor()
values: the values used to generate colors from the palette function
na.label: the legend label for NAs in values
bins: an approximate number of tick-marks on the color gradient for the colorNumeric palette if it is of length one; you can also provide a numeric vector as the pre-defined breaks (equally spaced)
colors: a vector of (HTML) colors to be used in the legend if pal is not provided
opacity: the opacity of colors
labels: a vector of text labels in the legend corresponding to colors
labFormat: a function to format the labels derived from pal and values (see Details below to know what labelFormat() returns by default; you can either use the helper function labelFormat(), or write your own function)
title: the legend title
className: extra CSS classes to append to the control, space separated
layerId: the ID of the legend; subsequent calls to addLegend() or addControl() with the same layerId will replace this legend. The ID can also be used with removeControl().
group: group name of a leaflet layer group. Supplying this value will tie the legend to the leaflet layer group with this name and will auto add/remove the legend as the group is added/removed, for example via layerControl(). You will need to set the group when you add a layer (e.g., addPolygons()) and supply the same name here.
data: the data object from which the argument values are derived; by default, it is the data object provided to leaflet() initially, but can be overridden
prefix: a prefix of legend labels
suffix: a suffix of legend labels
between: a separator between x[i] and x[i + 1] in legend labels (by default, it is a dash)
digits: the number of digits of numeric values in labels
big.mark: the thousand separator
transform: a function to transform the label value

Details

The labFormat argument is a function that takes the argument type = c("numeric", "bin", "quantile", "factor"), plus, arguments for different types of color palettes. For the colorNumeric() palette, labFormat takes a single argument, which is the breaks of the numeric vector, and returns a character vector of the same length. For colorBin(), labFormat also takes a vector of breaks of length n but should return a character vector of length n - 1, with the i-th element representing the interval c(x[i], x[i + 1]). For colorQuantile(), labFormat takes two arguments, the quantiles and the associated probabilities (each of length n), and should return a character vector of length n - 1 (similar to the colorBin() palette). For colorFactor(), labFormat takes one argument, the unique values of the factor, and should return a character vector of the same length.

By default, labFormat is basically format(scientific = FALSE, big.mark = ",") for the numeric palette, as.character() for the factor palette, and a function to return labels of the form x[i] - x[i + 1] for bin and quantile palettes (in the case of quantile palettes, x is the probabilities instead of the values of breaks).

Examples

# !formatR
library(leaflet)
# a manual legend
leaflet() %>% addTiles() %>% addLegend(
  position = "bottomright",
  colors = rgb(t(col2rgb(palette())) / 255),
  labels = palette(), opacity = 1,
  title = "An Obvious Legend"
)


# \donttest{

# an automatic legend derived from the color palette
df <- local({
  n <- 300; x <- rnorm(n); y <- rnorm(n)
  z <- sqrt(x ^ 2 + y ^ 2); z[sample(n, 10)] <- NA
  data.frame(x, y, z)
})
pal <- colorNumeric("OrRd", df$z)
leaflet(df) %>%
  addTiles() %>%
  addCircleMarkers(~x, ~y, color = ~pal(z), group = "circles") %>%
  addLegend(pal = pal, values = ~z, group = "circles", position = "bottomleft") %>%
  addLayersControl(overlayGroups = c("circles"))


# format legend labels
df <- data.frame(x = rnorm(100), y = rexp(100, 2), z = runif(100))
pal <- colorBin("PuOr", df$z, bins = c(0, .1, .4, .9, 1))
leaflet(df) %>%
  addTiles() %>%
  addCircleMarkers(~x, ~y, color = ~pal(z), group = "circles") %>%
  addLegend(pal = pal, values = ~z, group = "circles", position = "bottomleft") %>%
  addLayersControl(overlayGroups = c("circles"))


leaflet(df) %>%
  addTiles() %>%
  addCircleMarkers(~x, ~y, color = ~pal(z), group = "circles") %>%
  addLegend(pal = pal, values = ~z, labFormat = labelFormat(
    prefix = "(", suffix = ")%", between = ", ",
    transform = function(x) 100 * x
  ),  group = "circles", position = "bottomleft" ) %>%
  addLayersControl(overlayGroups = c("circles"))

# }