map_legends: Add legends to maps with customizable styling

In mapgl: Interactive Maps with 'Mapbox GL JS' and 'MapLibre GL JS'

Add legends to maps with customizable styling

Description

These functions provide a comprehensive system for adding categorical and continuous legends to Mapbox GL and MapLibre GL maps, with extensive styling customization options.

Usage

legend_style(
  background_color = NULL,
  background_opacity = NULL,
  border_color = NULL,
  border_width = NULL,
  border_radius = NULL,
  text_color = NULL,
  text_size = NULL,
  title_color = NULL,
  title_size = NULL,
  font_family = NULL,
  title_font_family = NULL,
  font_weight = NULL,
  title_font_weight = NULL,
  element_border_color = NULL,
  element_border_width = NULL,
  shadow = NULL,
  shadow_color = NULL,
  shadow_size = NULL,
  padding = NULL
)

add_legend(
  map,
  legend_title,
  values,
  colors,
  type = c("continuous", "categorical"),
  circular_patches = FALSE,
  position = "top-left",
  sizes = NULL,
  add = FALSE,
  unique_id = NULL,
  width = NULL,
  layer_id = NULL,
  margin_top = NULL,
  margin_right = NULL,
  margin_bottom = NULL,
  margin_left = NULL,
  style = NULL
)

add_categorical_legend(
  map,
  legend_title,
  values,
  colors,
  circular_patches = FALSE,
  position = "top-left",
  unique_id = NULL,
  sizes = NULL,
  add = FALSE,
  width = NULL,
  layer_id = NULL,
  margin_top = NULL,
  margin_right = NULL,
  margin_bottom = NULL,
  margin_left = NULL,
  style = NULL
)

add_continuous_legend(
  map,
  legend_title,
  values,
  colors,
  position = "top-left",
  unique_id = NULL,
  add = FALSE,
  width = NULL,
  layer_id = NULL,
  margin_top = NULL,
  margin_right = NULL,
  margin_bottom = NULL,
  margin_left = NULL,
  style = NULL
)

clear_legend(map, legend_ids = NULL)

Arguments

background_color	Background color for the legend container (e.g., "white", "#ffffff").
background_opacity	Opacity of the legend background (0-1, where 1 is fully opaque).
border_color	Color of the legend border (e.g., "black", "#000000").
border_width	Width of the legend border in pixels.
border_radius	Border radius for rounded corners in pixels.
text_color	Color of the legend text (e.g., "black", "#000000").
text_size	Size of the legend text in pixels.
title_color	Color of the legend title text.
title_size	Size of the legend title text in pixels.
font_family	Font family for legend text (e.g., "Arial", "Times New Roman", "Open Sans").
title_font_family	Font family for legend title (defaults to font_family if not specified).
font_weight	Font weight for legend text (e.g., "normal", "bold", "lighter", or numeric like 400, 700).
title_font_weight	Font weight for legend title (defaults to font_weight if not specified).
element_border_color	Color for borders around legend elements (color bar for continuous, patches/circles for categorical).
element_border_width	Width in pixels for borders around legend elements.
shadow	Logical, whether to add a drop shadow to the legend.
shadow_color	Color of the drop shadow (e.g., "black", "rgba(0,0,0,0.3)").
shadow_size	Size/blur radius of the drop shadow in pixels.
padding	Internal padding of the legend container in pixels.
map	A map object created by the mapboxgl or maplibre function.
legend_title	The title of the legend.
values	The values being represented on the map (either a vector of categories or a vector of stops).
colors	The corresponding colors for the values (either a vector of colors, a single color, or an interpolate function).
type	One of "continuous" or "categorical" (for add_legend only).
circular_patches	Logical, whether to use circular patches in the legend (only for categorical legends).
position	The position of the legend on the map (one of "top-left", "bottom-left", "top-right", "bottom-right").
sizes	An optional numeric vector of sizes for the legend patches, or a single numeric value (only for categorical legends).
add	Logical, whether to add this legend to existing legends (TRUE) or replace existing legends (FALSE). Default is FALSE.
unique_id	Optional. A unique identifier for the legend. If not provided, a random ID will be generated.
width	The width of the legend. Can be specified in pixels (e.g., "250px") or as "auto". Default is NULL, which uses the built-in default.
layer_id	The ID of the layer that this legend is associated with. If provided, the legend will be shown/hidden when the layer visibility is toggled.
margin_top	Custom top margin in pixels, allowing for fine control over legend positioning. Default is NULL (uses standard positioning).
margin_right	Custom right margin in pixels. Default is NULL.
margin_bottom	Custom bottom margin in pixels. Default is NULL.
margin_left	Custom left margin in pixels. Default is NULL.
style	Optional styling options created by legend_style() or a list of style options.
legend_ids	Optional. A character vector of legend IDs to clear (for clear_legend only). If not provided, all legends will be cleared.

Value

add_legend, add_categorical_legend, add_continuous_legend

The updated map object with the legend added.

legend_style

A list of class "mapgl_legend_style" containing the styling options.

clear_legend

The updated map object with the specified legend(s) cleared.

Legend Styling

The legend_style() function creates user-friendly styling options:

Container styling

background_color, background_opacity, border_color, border_width, border_radius, padding

Typography

font_family, title_font_family, font_weight, title_font_weight, text_color, title_color, text_size, title_size

Element borders

element_border_color, element_border_width (for patches/circles and color bars)

Shadows

shadow, shadow_color, shadow_size

Examples

## Not run: 
# Basic categorical legend
add_legend(map, "Population", 
          values = c("Low", "Medium", "High"),
          colors = c("blue", "yellow", "red"),
          type = "categorical")

# Continuous legend with custom styling using legend_style()
add_legend(map, "Income", 
          values = c(0, 50000, 100000),
          colors = c("blue", "yellow", "red"),
          type = "continuous",
          style = legend_style(
            background_color = "white",
            background_opacity = 0.9,
            border_width = 2,
            border_color = "navy",
            text_color = "darkblue",
            font_family = "Times New Roman",
            title_font_weight = "bold"
          ))
          
# Legend with custom styling using a list
add_legend(map, "Temperature", 
          values = c(0, 50, 100),
          colors = c("blue", "yellow", "red"),
          type = "continuous",
          style = list(
            background_color = "#f0f0f0",
            title_size = 16,
            text_size = 12,
            shadow = TRUE,
            shadow_color = "rgba(0,0,0,0.1)",
            shadow_size = 8
          ))

# Dark legend with white element borders
add_legend(map, "Elevation", 
          values = c(0, 1000, 2000, 3000),
          colors = c("#2c7bb6", "#abd9e9", "#fdae61", "#d7191c"),
          type = "continuous",
          style = legend_style(
            background_color = "#2c3e50",
            text_color = "white",
            title_color = "white",
            element_border_color = "white",
            element_border_width = 1
          ))
          
# Categorical legend with circular patches and styling
add_categorical_legend(
    map = map,
    legend_title = "Population",
    values = c("Low", "Medium", "High"),
    colors = c("#FED976", "#FEB24C", "#FD8D3C"),
    circular_patches = TRUE,
    sizes = c(10, 15, 20),
    style = legend_style(
      background_opacity = 0.95,
      border_width = 1,
      border_color = "gray",
      title_color = "navy",
      element_border_color = "black",
      element_border_width = 1
    )
)

# Create reusable legend styling
dark_style <- legend_style(
  background_color = "#2c3e50",
  text_color = "white",
  title_color = "white",
  font_family = "Arial",
  title_font_weight = "bold",
  element_border_color = "white",
  element_border_width = 1,
  shadow = TRUE,
  shadow_color = "rgba(0,0,0,0.3)",
  shadow_size = 6
)

# Clear specific legends
clear_legend(map_proxy, legend_ids = c("legend-1", "legend-2"))

## End(Not run)

mapgl documentation built on June 16, 2025, 5:09 p.m.