Add a color legend to a map

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.

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 = " – ",
  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"))

# }