addLegend {leaflet} | R Documentation

## Add a color legend to a map

### Description

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 `NA`s 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"
    )

    # 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"))

[Package leaflet version 2.0.1 Index]