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, labFormat = labelFormat(), title = NULL,
      className = "info legend", layerId = NULL)

    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`.
`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) %>%
      addCircleMarkers(~x, ~y, color = ~pal(z)) %>%
      addLegend(pal = pal, values = ~z)

    # 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) %>%
      addCircleMarkers(~x, ~y, color = ~pal(z)) %>%
      addLegend(pal = pal, values = ~z)

    leaflet(df) %>%
      addCircleMarkers(~x, ~y, color = ~pal(z)) %>%
      addLegend(pal = pal, values = ~z, labFormat = labelFormat(
        prefix = '(', suffix = ')%', between = ', ',
        transform = function(x) 100 * x
      ))

[Package leaflet version 1.1.0 Index]