Package 'mapgl'

Description

Add a bivariate legend

Usage

add_bivariate_legend(
  map,
  scale,
  legend_title = NULL,
  x_title = NULL,
  y_title = NULL,
  position = "top-left",
  width = NULL,
  style = NULL,
  add = FALSE,
  unique_id = NULL,
  layer_id = NULL,
  target = "compare",
  draggable = FALSE,
  collapsible = FALSE,
  collapsed = FALSE
)

Arguments

Value

The updated map object.

Description

Add a circle layer to a Mapbox GL map

Usage

add_circle_layer(
  map,
  id,
  source,
  source_layer = NULL,
  circle_blur = NULL,
  circle_color = NULL,
  circle_emissive_strength = NULL,
  circle_opacity = NULL,
  circle_pitch_alignment = NULL,
  circle_pitch_scale = NULL,
  circle_radius = NULL,
  circle_sort_key = NULL,
  circle_stroke_color = NULL,
  circle_stroke_opacity = NULL,
  circle_stroke_width = NULL,
  circle_translate = NULL,
  circle_translate_anchor = "map",
  visibility = "visible",
  slot = NULL,
  min_zoom = NULL,
  max_zoom = NULL,
  popup = NULL,
  tooltip = NULL,
  hover_options = NULL,
  before_id = NULL,
  filter = NULL,
  cluster_options = NULL
)

Arguments

Value

The modified map object with the new circle layer added.

Examples

## Not run: 
library(mapgl)
library(sf)
library(dplyr)

# Set seed for reproducibility
set.seed(1234)

# Define the bounding box for Washington DC (approximately)
bbox <- st_bbox(
    c(
        xmin = -77.119759,
        ymin = 38.791645,
        xmax = -76.909393,
        ymax = 38.995548
    ),
    crs = st_crs(4326)
)

# Generate 30 random points within the bounding box
random_points <- st_as_sf(
    data.frame(
        id = 1:30,
        lon = runif(30, bbox["xmin"], bbox["xmax"]),
        lat = runif(30, bbox["ymin"], bbox["ymax"])
    ),
    coords = c("lon", "lat"),
    crs = 4326
)

# Assign random categories
categories <- c("music", "bar", "theatre", "bicycle")
random_points <- random_points %>%
    mutate(category = sample(categories, n(), replace = TRUE))

# Map with circle layer
mapboxgl(style = mapbox_style("light")) %>%
    fit_bounds(random_points, animate = FALSE) %>%
    add_circle_layer(
        id = "poi-layer",
        source = random_points,
        circle_color = match_expr(
            "category",
            values = c(
                "music", "bar", "theatre",
                "bicycle"
            ),
            stops = c(
                "#1f78b4", "#33a02c",
                "#e31a1c", "#ff7f00"
            )
        ),
        circle_radius = 8,
        circle_stroke_color = "#ffffff",
        circle_stroke_width = 2,
        circle_opacity = 0.8,
        tooltip = "category",
        hover_options = list(
            circle_radius = 12,
            circle_color = "#ffff99"
        )
    ) %>%
    add_categorical_legend(
        legend_title = "Points of Interest",
        values = c("Music", "Bar", "Theatre", "Bicycle"),
        colors = c("#1f78b4", "#33a02c", "#e31a1c", "#ff7f00"),
        circular_patches = TRUE
    )

## End(Not run)

Description

This function adds a custom control to a Mapbox GL or MapLibre GL map. It allows you to create custom HTML element controls and add them to the map.

Usage

add_control(
  map,
  html,
  position = "top-right",
  className = NULL,
  id = NULL,
  ...
)

Arguments

Value

The modified map object with the custom control added.

Examples

## Not run: 
library(mapgl)

# Basic custom control
maplibre() |>
  add_control(
    html = "<div style='background-color: white; padding: 5px;'>
             <p>Custom HTML</p>
             <img src='path/to/image.png' alt='image'/>
            </div>",
    position = "top-left"
  )

# Custom control with specific ID for selective removal
maplibre() |>
  add_control(
    html = "<div style='background: blue; color: white; padding: 10px;'>
             My Control
            </div>",
    position = "top-right",
    id = "my_custom_control"
  )

# Later, remove only this specific control
maplibre_proxy("map") |>
  clear_controls("my_custom_control")

## End(Not run)

Description

This function adds a compact control that displays the cursor position as longitude and latitude in WGS84 coordinates.

Usage

add_coordinates_control(
  map,
  position = "bottom-right",
  format = c("decimal", "dms"),
  precision = NULL,
  label = NULL,
  empty_text = "Move cursor over map",
  wrap = TRUE
)

Arguments

Value

The modified map object with the coordinates control added.

Examples

## Not run: 
library(mapgl)

maplibre() |>
  add_coordinates_control()

mapboxgl() |>
  add_coordinates_control(
    position = "bottom-left",
    format = "dms",
    precision = 2,
    label = "Longitude, latitude"
  )

## End(Not run)

Description

Add a draw control to a map

Usage

add_draw_control(
  map,
  position = "top-left",
  freehand = FALSE,
  simplify_freehand = FALSE,
  rectangle = FALSE,
  radius = FALSE,
  bezier = FALSE,
  bezier_polygon = FALSE,
  orientation = "vertical",
  source = NULL,
  attributes = NULL,
  point_color = "#3bb2d0",
  line_color = "#3bb2d0",
  fill_color = "#3bb2d0",
  fill_opacity = 0.1,
  active_color = "#fbb03b",
  vertex_radius = 5,
  line_width = 2,
  download_button = FALSE,
  download_filename = "drawn-features",
  show_measurements = FALSE,
  measurement_units = "both",
  ...
)

Arguments

Details

Bezier drawing modes are supported when the draw control is added to the original map widget or later through a regular Shiny map proxy. Compare widgets and compare proxies are not yet supported for Bezier modes.

To draw Bezier curves, click the Bezier button, then use Alt + left-drag to create nodes with handles. A plain left-click creates nodes without handles. Press Enter, or click the last node, to finish the curve. In direct select mode, select a node and drag its handles to edit the curve; use Alt + drag on a handle to break handle symmetry.

Retrieved Bezier features are returned to R as standard sf geometries using the rendered curved coordinates: Bezier curves become LineString features and Bezier polygons become Polygon features. The Bezier control metadata is also preserved in feature-property columns so the browser widget can continue to edit those features as Bezier objects.

When attributes is supplied, selecting exactly one drawn feature opens a small attribute editor. Click Save to write values to the feature properties; get_drawn_features() returns those properties as sf columns. The editor works for newly drawn features and features loaded into the draw control with source or add_features_to_draw(). Compare widgets are not yet supported for attribute editing.

Value

The modified map object with the draw control added.

Examples

## Not run: 
library(mapgl)

mapboxgl(
    style = mapbox_style("streets"),
    center = c(-74.50, 40),
    zoom = 9
) |>
    add_draw_control()

# With initial features from a source
library(tigris)
tx <- counties(state = "TX", cb = TRUE)
mapboxgl(bounds = tx) |>
    add_source(id = "tx", data = tx) |>
    add_draw_control(source = "tx")

# With custom styling
mapboxgl() |>
    add_draw_control(
        point_color = "#ff0000",
        line_color = "#00ff00",
        fill_color = "#0000ff",
        fill_opacity = 0.3,
        active_color = "#ff00ff",
        vertex_radius = 7,
        line_width = 3
    )

# Enable rectangle drawing mode
mapboxgl() |>
    add_draw_control(rectangle = TRUE)

# Enable radius/circle drawing mode
mapboxgl() |>
    add_draw_control(radius = TRUE)

# Enable Bezier curve drawing mode
mapboxgl() |>
    add_draw_control(bezier = TRUE)

# Add an attribute editor for classification workflows
mapboxgl() |>
    add_draw_control(
        attributes = list(
            class = draw_attribute(
                "select",
                choices = c("forest", "water", "urban"),
                required = TRUE
            ),
            notes = draw_attribute("textarea"),
            confidence = draw_attribute(
                "numeric",
                min = 0,
                max = 1,
                step = 0.1,
                default = 1
            )
        )
    )

# Enable multiple drawing modes
mapboxgl() |>
    add_draw_control(
        freehand = TRUE,
        rectangle = TRUE,
        radius = TRUE,
        bezier = TRUE
    )

## End(Not run)

Description

This function adds features from an existing source to a draw control on a map.

Usage

add_features_to_draw(map, source, clear_existing = FALSE)

Arguments

Value

The modified map object

Examples

## Not run: 
library(mapgl)
library(tigris)

# Add features from an existing source
tx <- counties(state = "TX", cb = TRUE)
mapboxgl(bounds = tx) |>
  add_source(id = "tx", data = tx) |>
  add_draw_control() |>
  add_features_to_draw(source = "tx")

# In a Shiny app
observeEvent(input$load_data, {
  mapboxgl_proxy("map") |>
    add_features_to_draw(
      source = "dynamic_data",
      clear_existing = TRUE
    )
})

## End(Not run)

Description

Add a fill-extrusion layer to a Mapbox GL map

Usage

add_fill_extrusion_layer(
  map,
  id,
  source,
  source_layer = NULL,
  fill_extrusion_ambient_occlusion_intensity = NULL,
  fill_extrusion_ambient_occlusion_radius = NULL,
  fill_extrusion_base = NULL,
  fill_extrusion_cast_shadows = NULL,
  fill_extrusion_color = NULL,
  fill_extrusion_cutoff_fade_range = NULL,
  fill_extrusion_emissive_strength = NULL,
  fill_extrusion_height = NULL,
  fill_extrusion_opacity = NULL,
  fill_extrusion_pattern = NULL,
  fill_extrusion_translate = NULL,
  fill_extrusion_translate_anchor = "map",
  fill_extrusion_vertical_gradient = NULL,
  visibility = "visible",
  slot = NULL,
  min_zoom = NULL,
  max_zoom = NULL,
  popup = NULL,
  tooltip = NULL,
  hover_options = NULL,
  before_id = NULL,
  filter = NULL
)

Arguments

Value

The modified map object with the new fill-extrusion layer added.

Examples

## Not run: 
library(mapgl)

maplibre(
    style = maptiler_style("basic"),
    center = c(-74.0066, 40.7135),
    zoom = 15.5,
    pitch = 45,
    bearing = -17.6
) |>
    add_vector_source(
        id = "openmaptiles",
        url = paste0(
            "https://api.maptiler.com/tiles/v3/tiles.json?key=",
            Sys.getenv("MAPTILER_API_KEY")
        )
    ) |>
    add_fill_extrusion_layer(
        id = "3d-buildings",
        source = "openmaptiles",
        source_layer = "building",
        fill_extrusion_color = interpolate(
            column = "render_height",
            values = c(0, 200, 400),
            stops = c("lightgray", "royalblue", "lightblue")
        ),
        fill_extrusion_height = list(
            "interpolate",
            list("linear"),
            list("zoom"),
            15,
            0,
            16,
            list("get", "render_height")
        )
    )

## End(Not run)

Description

Add a fill layer to a map

Usage

add_fill_layer(
  map,
  id,
  source,
  source_layer = NULL,
  fill_antialias = TRUE,
  fill_color = NULL,
  fill_emissive_strength = NULL,
  fill_opacity = NULL,
  fill_outline_color = NULL,
  fill_pattern = NULL,
  fill_pattern_cross_fade = NULL,
  fill_sort_key = NULL,
  fill_translate = NULL,
  fill_translate_anchor = "map",
  fill_z_offset = NULL,
  visibility = "visible",
  slot = NULL,
  min_zoom = NULL,
  max_zoom = NULL,
  popup = NULL,
  tooltip = NULL,
  hover_options = NULL,
  before_id = NULL,
  filter = NULL
)

Arguments

Value

The modified map object with the new fill layer added.

Examples

## Not run: 
library(tidycensus)

fl_age <- get_acs(
    geography = "tract",
    variables = "B01002_001",
    state = "FL",
    year = 2022,
    geometry = TRUE
)

mapboxgl() |>
    fit_bounds(fl_age, animate = FALSE) |>
    add_fill_layer(
        id = "fl_tracts",
        source = fl_age,
        fill_color = interpolate(
            column = "estimate",
            values = c(20, 80),
            stops = c("lightblue", "darkblue"),
            na_color = "lightgrey"
        ),
        fill_opacity = 0.5
    )

## End(Not run)

Description

Adds a FlowmapGL layer for visualizing origin-destination flows between point locations.

Usage

add_flowmap(
  map,
  id,
  locations,
  flows,
  flow_color_scheme = "Teal",
  flow_opacity = 1,
  flow_dark_mode = "auto",
  flow_blend = "auto",
  flow_fade_amount = 50,
  flow_highlight_color = "#ff9b29",
  flow_locations_enabled = TRUE,
  flow_location_totals_enabled = TRUE,
  flow_location_labels_enabled = FALSE,
  flow_lines_rendering_mode = c("straight", "animated-straight", "curved"),
  flow_line_thickness_scale = 1,
  flow_line_curviness = 1,
  flow_clustering_enabled = TRUE,
  flow_clustering_auto = TRUE,
  flow_clustering_level = NULL,
  flow_fade_enabled = TRUE,
  flow_fade_opacity_enabled = FALSE,
  flow_adaptive_scales_enabled = TRUE,
  flow_temporal_scale_domain = c("selected", "all"),
  flow_max_top_flows_display_num = 5000,
  flow_endpoints_in_viewport_mode = c("any", "both"),
  flow_time_column = NULL,
  flow_selected_time_range = NULL,
  flow_selected_locations = NULL,
  flow_location_filter_mode = c("ALL", "INCOMING", "OUTGOING", "BETWEEN"),
  tooltip = TRUE,
  popup = FALSE,
  tooltip_style = c("floating", "anchored"),
  popup_style = c("floating", "anchored"),
  tooltip_theme = c("auto", "light", "dark"),
  popup_theme = c("auto", "light", "dark"),
  tooltip_options = list(),
  popup_options = list(),
  visibility = c("visible", "none"),
  before_id = NULL,
  slot = NULL
)

Arguments

Details

Mapbox and MapLibre layer paint arguments such as fill_color, circle_color, and line_color require a scalar CSS color or a style expression. Use interpolate_palette(...)$expression for data-driven layer color ramps. FlowMapGL's flow_color_scheme accepts a preset name such as "Teal", a plain color ramp such as c("red", "white", "blue"), or an interpolate_palette(...) scale object.

Flow scale domains have separate spatial and temporal controls. flow_adaptive_scales_enabled = TRUE rescales flow thickness and color for the current viewport; FALSE keeps the scale tied to the broader map extent. For temporal flowmaps, flow_temporal_scale_domain = "selected" rescales within the selected time-control interval, while "all" keeps the scale comparable across the full time extent.

Value

The modified map object with the flowmap layer added.

Examples

# Create a flowmap centered on Montréal using the bundled datasets
maplibre(
  style = carto_style("dark-matter"),
  center = c(-73.58, 45.50),
  zoom = 11,
  projection = "mercator"
) |>
  add_flowmap(
    id = "bixi-rides",
    locations = bixi_locations,
    flows = bixi_flows,
    flow_time_column = "time",
    flow_color_scheme = "Teal",
    flow_dark_mode = TRUE
  ) |>
  add_time_control(
    data = bixi_flows,
    time_column = "time",
    time_interval = "hour",
    title = "BIXI Montréal Rides"
  )

Description

Add a fullscreen control to a map

Usage

add_fullscreen_control(map, position = "top-right")

Arguments

Value

The modified map object with the fullscreen control added.

Examples

## Not run: 
library(mapgl)

maplibre(
    style = maptiler_style("streets"),
    center = c(11.255, 43.77),
    zoom = 13
) |>
    add_fullscreen_control(position = "top-right")

## End(Not run)

Description

This function adds a Geocoder search bar to a Mapbox GL or MapLibre GL map. By default, a marker will be added at the selected location and the map will fly to that location. The results of the geocode are accessible in a Shiny session at input$MAPID_geocoder$result, where MAPID is the name of your map.

Usage

add_geocoder_control(
  map,
  position = "top-right",
  placeholder = "Search",
  collapsed = FALSE,
  provider = NULL,
  maptiler_api_key = NULL,
  ...
)

Arguments

Value

The modified map object with the geocoder control added.

Examples

## Not run: 
library(mapgl)

mapboxgl() |>
    add_geocoder_control(position = "top-left", placeholder = "Enter an address")

maplibre() |>
    add_geocoder_control(position = "top-right", placeholder = "Search location")

# Using MapTiler geocoder
maplibre() |>
    add_geocoder_control(provider = "maptiler", maptiler_api_key = "YOUR_API_KEY")

## End(Not run)

Description

This function adds a Geolocate control to a Mapbox GL or MapLibre GL map. The geolocate control allows users to track their current location on the map.

Usage

add_geolocate_control(
  map,
  position = "top-right",
  track_user = FALSE,
  show_accuracy_circle = TRUE,
  show_user_location = TRUE,
  show_user_heading = FALSE,
  fit_bounds_options = list(maxZoom = 15),
  position_options = list(enableHighAccuracy = FALSE, timeout = 6000)
)

Arguments

Value

The modified map object with the geolocate control added.

Examples

## Not run: 
library(mapgl)

mapboxgl() |>
    add_geolocate_control(
        position = "top-right",
        track_user = TRUE,
        show_user_heading = TRUE
    )

## End(Not run)

Description

This function adds a globe control to a MapLibre GL map that allows toggling between "mercator" and "globe" projections with a single click.

Usage

add_globe_control(map, position = "top-right")

Arguments

Value

The modified map object with the globe control added.

Examples

## Not run: 
library(mapgl)

maplibre() |>
    add_globe_control(position = "top-right")

## End(Not run)

Description

This function adds a globe minimap control to a Mapbox GL or Maplibre map.

Usage

add_globe_minimap(
  map,
  position = "bottom-right",
  globe_size = 82,
  land_color = "white",
  water_color = "rgba(30 40 70/60%)",
  marker_color = "#ff2233",
  marker_size = 1
)

Arguments

Value

The modified map object with the globe minimap added.

Examples

## Not run: 
library(mapgl)

m <- mapboxgl() %>%
    add_globe_minimap()

m <- maplibre() %>%
    add_globe_minimap()

## End(Not run)

Description

Add a hexagon source from the H3 geospatial indexing system.

Usage

add_h3j_source(map, id, url)

Arguments

References

https://h3geo.org, https://github.com/INSPIDE/h3j-h3t

Examples

url = "https://inspide.github.io/h3j-h3t/examples/h3j/sample.h3j"
maplibre(center=c(-3.704, 40.417), zoom=15, pitch=30) |>
  add_h3j_source("h3j_testsource",
                  url = url
  )  |>
  add_fill_extrusion_layer(
    id = "h3j_testlayer",
    source = "h3j_testsource",
    fill_extrusion_color = interpolate(
      column = "value",
      values = c(0, 21.864),
      stops = c("#430254", "#f83c70")
    ),
    fill_extrusion_height = list(
      "interpolate",
      list("linear"),
      list("zoom"),
      14,
      0,
      15.05,
      list("*", 10, list("get", "value"))
    ),
    fill_extrusion_opacity = 0.7
  )

Description

Add a heatmap layer to a Mapbox GL map

Usage

add_heatmap_layer(
  map,
  id,
  source,
  source_layer = NULL,
  heatmap_color = NULL,
  heatmap_intensity = NULL,
  heatmap_opacity = NULL,
  heatmap_radius = NULL,
  heatmap_weight = NULL,
  visibility = "visible",
  slot = NULL,
  min_zoom = NULL,
  max_zoom = NULL,
  before_id = NULL,
  filter = NULL
)

Arguments

Value

The modified map object with the new heatmap layer added.

Examples

## Not run: 
library(mapgl)

mapboxgl(
    style = mapbox_style("dark"),
    center = c(-120, 50),
    zoom = 2
) |>
    add_heatmap_layer(
        id = "earthquakes-heat",
        source = list(
            type = "geojson",
            data = "https://docs.mapbox.com/mapbox-gl-js/assets/earthquakes.geojson"
        ),
        heatmap_weight = interpolate(
            column = "mag",
            values = c(0, 6),
            stops = c(0, 1)
        ),
        heatmap_intensity = interpolate(
            property = "zoom",
            values = c(0, 9),
            stops = c(1, 3)
        ),
        heatmap_color = interpolate(
            property = "heatmap-density",
            values = seq(0, 1, 0.2),
            stops = c(
                "rgba(33,102,172,0)", "rgb(103,169,207)",
                "rgb(209,229,240)", "rgb(253,219,199)",
                "rgb(239,138,98)", "rgb(178,24,43)"
            )
        ),
        heatmap_opacity = 0.7
    )

## End(Not run)

Description

This function adds an image to the map's style. The image can be used with icon-image, background-pattern, fill-pattern, or line-pattern. It can also be used with a style list, such as one created by basemap_style(), before the style is supplied to maplibre() or mapboxgl().

Usage

add_image(
  map,
  id,
  url,
  content = NULL,
  pixel_ratio = 1,
  sdf = FALSE,
  stretch_x = NULL,
  stretch_y = NULL
)

Arguments

Value

The modified map object or style list with the image added.

Examples

## Not run: 
library(mapgl)

# Path to your local image file OR a URL to a remote image file
# that is not blocked by CORS restrictions
image_path <- "/path/to/your/image.png"

pts <- tigris::landmarks("DE")[1:100, ]

maplibre(bounds = pts) |>
    add_image("local_icon", image_path) |>
    add_symbol_layer(
        id = "local_icons",
        source = pts,
        icon_image = "local_icon",
        icon_size = 0.5,
        icon_allow_overlap = TRUE
    )

## End(Not run)

Description

Add an image source to a Mapbox GL or Maplibre GL map

Usage

add_image_source(
  map,
  id,
  url = NULL,
  data = NULL,
  coordinates = NULL,
  colors = NULL
)

Arguments

Value

The modified map object with the new source added.

Description

In many cases, you will use add_layer() internal to other layer-specific functions in mapgl. Advanced users will want to use add_layer() for more fine-grained control over the appearance of their layers.

Usage

add_layer(
  map,
  id,
  type = "fill",
  source,
  source_layer = NULL,
  paint = list(),
  layout = list(),
  slot = NULL,
  min_zoom = NULL,
  max_zoom = NULL,
  popup = NULL,
  tooltip = NULL,
  hover_options = NULL,
  before_id = NULL,
  filter = NULL
)

Arguments

Value

The modified map object with the new layer added.

Examples

## Not run: 
# Load necessary libraries
library(mapgl)
library(tigris)

# Load geojson data for North Carolina tracts
nc_tracts <- tracts(state = "NC", cb = TRUE)

# Create a Mapbox GL map
map <- mapboxgl(
    style = mapbox_style("light"),
    center = c(-79.0193, 35.7596),
    zoom = 7
)

# Add a source and fill layer for North Carolina tracts
map %>%
    add_source(
        id = "nc-tracts",
        data = nc_tracts
    ) %>%
    add_layer(
        id = "nc-layer",
        type = "fill",
        source = "nc-tracts",
        paint = list(
            "fill-color" = "#888888",
            "fill-opacity" = 0.4
        )
    )

## End(Not run)

Description

This function adds an interactive live customization widget (using lil-gui) to the map. It allows users to customize paint and layout properties of map layers in real-time.

Usage

add_layer_tuner(
  map,
  layers = "all",
  show_all_args = FALSE,
  title = NULL,
  position = "top-left",
  width = 245,
  height = NULL,
  collapsed = FALSE
)

Arguments

Value

The modified map object with the layer tuner added.

Examples

# Create a flowmap centered on Montréal using the bundled datasets and add a layer tuner
maplibre(
  style = carto_style("dark-matter"),
  center = c(-73.58, 45.50),
  zoom = 11,
  projection = "mercator"
) |>
  add_flowmap(
    id = "bixi-rides",
    locations = bixi_locations,
    flows = bixi_flows,
    flow_time_column = "time",
    flow_color_scheme = "Teal",
    flow_dark_mode = TRUE
  ) |>
  add_layer_tuner(position = "top-right", width = 320)

Description

Add a layers control to the map

Usage

add_layers_control(
  map,
  position = "top-left",
  layers = NULL,
  collapsible = TRUE,
  use_icon = TRUE,
  background_color = NULL,
  active_color = NULL,
  hover_color = NULL,
  active_text_color = NULL,
  inactive_text_color = NULL,
  margin_top = NULL,
  margin_right = NULL,
  margin_bottom = NULL,
  margin_left = NULL
)

Arguments

Value

The modified map object with the layers control added.

Examples

## Not run: 
library(tigris)
options(tigris_use_cache = TRUE)

rds <- roads("TX", "Tarrant")
tr <- tracts("TX", "Tarrant", cb = TRUE)
cty <- counties("TX", cb = TRUE)

maplibre() |>
    fit_bounds(rds) |>
    add_fill_layer(
        id = "Census tracts",
        source = tr,
        fill_color = "purple",
        fill_opacity = 0.6
    ) |>
    add_line_layer(
        "Local roads",
        source = rds,
        line_color = "pink"
    ) |>
    add_layers_control(
        position = "top-left",
        background_color = "#ffffff",
        active_color = "#4a90e2"
    )

# With custom labels
maplibre() |>
    add_fill_layer(id = "tract-fill", source = tr) |>
    add_line_layer(id = "tract-line", source = tr) |>
    add_layers_control(
        layers = list(
            "Census Tracts" = "tract-fill",
            "Tract Borders" = "tract-line"
        )
    )

# Group multiple layers together
maplibre(bounds = cty) |>
    add_fill_layer(id = "county-fill", source = cty, fill_opacity = 0.3) |>
    add_line_layer(
        id = "county-outline",
        source = cty,
        line_color = "yellow",
        line_width = 3
    ) |>
    add_line_layer(
        id = "roads-layer",
        source = rds,
        line_color = "blue"
    ) |>
    add_layers_control(
        layers = list(
            "Counties" = c("county-fill", "county-outline"),
            "Roads" = "roads-layer"
        )
    )

## End(Not run)

Description

Add a line layer to a map

Usage

add_line_layer(
  map,
  id,
  source,
  source_layer = NULL,
  line_blur = NULL,
  line_cap = NULL,
  line_color = NULL,
  line_dasharray = NULL,
  line_elevation_ground_scale = NULL,
  line_elevation_reference = NULL,
  line_emissive_strength = NULL,
  line_gap_width = NULL,
  line_gradient = NULL,
  line_join = NULL,
  line_miter_limit = NULL,
  line_occlusion_opacity = NULL,
  line_offset = NULL,
  line_opacity = NULL,
  line_pattern = NULL,
  line_pattern_cross_fade = NULL,
  line_round_limit = NULL,
  line_sort_key = NULL,
  line_translate = NULL,
  line_translate_anchor = "map",
  line_trim_color = NULL,
  line_trim_fade_range = NULL,
  line_trim_offset = NULL,
  line_width = NULL,
  line_z_offset = NULL,
  visibility = "visible",
  slot = NULL,
  min_zoom = NULL,
  max_zoom = NULL,
  popup = NULL,
  tooltip = NULL,
  hover_options = NULL,
  before_id = NULL,
  filter = NULL
)

Arguments

Value

The modified map object with the new line layer added.

Examples

## Not run: 
library(mapgl)
library(tigris)

loving_roads <- roads("TX", "Loving")

maplibre(style = maptiler_style("backdrop")) |>
    fit_bounds(loving_roads) |>
    add_line_layer(
        id = "tracks",
        source = loving_roads,
        line_color = "navy",
        line_opacity = 0.7
    )

## End(Not run)

Description

Add markers to a Mapbox GL or Maplibre GL map

Usage

add_markers(
  map,
  data,
  color = "red",
  rotation = 0,
  popup = NULL,
  marker_id = NULL,
  draggable = FALSE,
  ...
)

Arguments

Value

The modified map object with the markers added.

Examples

## Not run: 
library(mapgl)
library(sf)

# Create a map object
map <- mapboxgl(
  style = mapbox_style("streets"),
  center = c(-74.006, 40.7128),
  zoom = 10
)

# Add a single draggable marker with an ID
map <- add_markers(
  map,
  c(-74.006, 40.7128),
  color = "blue",
  rotation = 45,
  popup = "A marker",
  draggable = TRUE,
  marker_id = "marker1"
)

# Add multiple markers from a named list of coordinates
coords_list <- list(marker2 = c(-74.006, 40.7128),
                    marker3 = c(-73.935242, 40.730610))
map <- add_markers(
  map,
  coords_list,
  color = "green",
  popup = "Multiple markers",
  draggable = TRUE
)

# Create an sf POINT object
points_sf <- st_as_sf(data.frame(
  id = c("marker4", "marker5"),
  lon = c(-74.006, -73.935242),
  lat = c(40.7128, 40.730610)
), coords = c("lon", "lat"), crs = 4326)
points_sf$popup <- c("Point 1", "Point 2")

# Add multiple markers from an sf object with IDs from a column
map <- add_markers(
  map,
  points_sf,
  color = "red",
  popup = "popup",
  draggable = TRUE,
  marker_id = "id"
)

## End(Not run)

Description

Add a navigation control to a map

Usage

add_navigation_control(
  map,
  show_compass = TRUE,
  show_zoom = TRUE,
  visualize_pitch = FALSE,
  position = "top-right",
  orientation = "vertical"
)

Arguments

Value

The updated map object with the navigation control added.

Examples

## Not run: 
library(mapgl)

mapboxgl() |>
    add_navigation_control(visualize_pitch = TRUE)

## End(Not run)

Description

Add a PMTiles source to a Mapbox GL or Maplibre GL map

Usage

add_pmtiles_source(
  map,
  id,
  url,
  source_type = "vector",
  maxzoom = 22,
  tilesize = 256,
  promote_id = NULL,
  ...
)

Arguments

Value

The modified map object with the new source added.

Examples

## Not run: 

# Visualize the Overture Maps places data as PMTiles
# Works with either `maplibre()` or `mapboxgl()`

library(mapgl)

maplibre(style = maptiler_style("basic", variant = "dark")) |>
  set_projection("globe") |>
  add_pmtiles_source(
    id = "places-source",
    url = "https://overturemaps-tiles-us-west-2-beta.s3.amazonaws.com/2025-06-25/places.pmtiles"
  ) |>
  add_circle_layer(
    id = "places-layer",
    source = "places-source",
    source_layer = "place",
    circle_color = "cyan",
    circle_opacity = 0.7,
    circle_radius = 4,
    tooltip = concat(
      "Name: ",
      get_column("@name"),
      "<br>Confidence: ",
      number_format(get_column("confidence"), maximum_fraction_digits = 2)
    )
  )

## End(Not run)

Description

Add a raster DEM source to a Mapbox GL or Maplibre GL map

Usage

add_raster_dem_source(map, id, url, tileSize = 512, maxzoom = NULL, ...)

Arguments

Value

The modified map object with the new source added.

Description

Add a raster layer to a Mapbox GL map

Usage

add_raster_layer(
  map,
  id,
  source,
  source_layer = NULL,
  raster_brightness_max = NULL,
  raster_brightness_min = NULL,
  raster_color = NULL,
  raster_color_mix = NULL,
  raster_color_range = NULL,
  raster_contrast = NULL,
  raster_emissive_strength = NULL,
  raster_fade_duration = NULL,
  raster_hue_rotate = NULL,
  raster_opacity = NULL,
  raster_resampling = NULL,
  raster_saturation = NULL,
  visibility = "visible",
  slot = NULL,
  min_zoom = NULL,
  max_zoom = NULL,
  before_id = NULL
)

Arguments

Value

The modified map object with the new raster layer added.

Examples

## Not run: 
mapboxgl(
    style = mapbox_style("dark"),
    zoom = 5,
    center = c(-75.789, 41.874)
) |>
    add_image_source(
        id = "radar",
        url = "https://docs.mapbox.com/mapbox-gl-js/assets/radar.gif",
        coordinates = list(
            c(-80.425, 46.437),
            c(-71.516, 46.437),
            c(-71.516, 37.936),
            c(-80.425, 37.936)
        )
    ) |>
    add_raster_layer(
        id = "radar-layer",
        source = "radar",
        raster_fade_duration = 0
    )

## End(Not run)

Description

Add a raster tile source to a Mapbox GL or Maplibre GL map

Usage

add_raster_source(
  map,
  id,
  url = NULL,
  tiles = NULL,
  tileSize = 256,
  maxzoom = 22,
  ...
)

Arguments

Value

The modified map object with the new source added.

Description

This function adds a reset control to a Mapbox GL or MapLibre GL map. The reset control allows users to return to the original zoom level and center.

Usage

add_reset_control(map, position = "top-right", animate = TRUE, duration = NULL)

Arguments

Value

The modified map object with the reset control added.

Examples

## Not run: 
library(mapgl)

mapboxgl() |>
    add_reset_control(position = "top-left")

## End(Not run)

Description

This function adds a scale control to a Mapbox GL or Maplibre GL map.

Usage

add_scale_control(
  map,
  position = "bottom-left",
  unit = "metric",
  max_width = 100
)

Arguments

Value

The modified map object with the scale control added.

Examples

## Not run: 
library(mapgl)

mapboxgl() |>
    add_scale_control(position = "bottom-right", unit = "imperial")

## End(Not run)

Description

This function adds a screenshot control to a Mapbox GL or MapLibre GL map. The screenshot control allows users to capture the map along with legends and attribution as a PNG image download.

Usage

add_screenshot_control(
  map,
  position = "top-right",
  filename = "map-screenshot",
  include_legend = TRUE,
  hide_controls = TRUE,
  include_scale_bar = TRUE,
  basemap_color = NULL,
  image_scale = 1,
  button_title = "Capture screenshot"
)

Arguments

Details

The screenshot is captured using html2canvas, which renders the map container including legends and attribution. Attribution is always included in screenshots to comply with map provider terms of service.

Most interactive controls (navigation, fullscreen, etc.) do not render correctly in screenshots due to SVG rendering limitations and will appear as blank boxes. The scale bar is an exception and renders correctly, which is why it is preserved by default via include_scale_bar = TRUE.

Value

The modified map object with the screenshot control added.

Examples

## Not run: 
library(mapgl)

# Basic usage
maplibre(style = carto_style("positron")) |>
  add_screenshot_control()

# With scale control (recommended for screenshots)
maplibre() |>
  add_scale_control(position = "bottom-left") |>
  add_screenshot_control()

# With custom filename
maplibre() |>
  add_fill_layer(
    id = "counties",
    source = list(type = "geojson", data = counties_sf)
  ) |>
  add_legend("Median Income", values = c("Low", "High")) |>
  add_screenshot_control(
    filename = "county-map",
    position = "top-left"
  )

# Exclude legend from screenshot
maplibre() |>
  add_screenshot_control(include_legend = FALSE)

## End(Not run)

Description

Add a GeoJSON or sf source to a Mapbox GL or Maplibre GL map

Usage

add_source(map, id, data, ...)

Arguments

Value

The modified map object with the new source added.

Description

Add a symbol layer to a map

Usage

add_symbol_layer(
  map,
  id,
  source,
  source_layer = NULL,
  icon_allow_overlap = NULL,
  icon_anchor = NULL,
  icon_color = NULL,
  icon_color_brightness_max = NULL,
  icon_color_brightness_min = NULL,
  icon_color_contrast = NULL,
  icon_color_saturation = NULL,
  icon_emissive_strength = NULL,
  icon_halo_blur = NULL,
  icon_halo_color = NULL,
  icon_halo_width = NULL,
  icon_ignore_placement = NULL,
  icon_image = NULL,
  icon_image_cross_fade = NULL,
  icon_keep_upright = NULL,
  icon_occlusion_opacity = NULL,
  icon_offset = NULL,
  icon_opacity = NULL,
  icon_optional = NULL,
  icon_padding = NULL,
  icon_pitch_alignment = NULL,
  icon_rotate = NULL,
  icon_rotation_alignment = NULL,
  icon_size = NULL,
  icon_text_fit = NULL,
  icon_text_fit_padding = NULL,
  icon_translate = NULL,
  icon_translate_anchor = NULL,
  symbol_avoid_edges = NULL,
  symbol_placement = NULL,
  symbol_sort_key = NULL,
  symbol_spacing = NULL,
  symbol_z_elevate = NULL,
  symbol_z_offset = NULL,
  symbol_z_order = NULL,
  text_allow_overlap = NULL,
  text_anchor = NULL,
  text_color = "black",
  text_emissive_strength = NULL,
  text_field = NULL,
  text_font = NULL,
  text_halo_blur = NULL,
  text_halo_color = NULL,
  text_halo_width = NULL,
  text_ignore_placement = NULL,
  text_justify = NULL,
  text_keep_upright = NULL,
  text_letter_spacing = NULL,
  text_line_height = NULL,
  text_max_angle = NULL,
  text_max_width = NULL,
  text_occlusion_opacity = NULL,
  text_offset = NULL,
  text_opacity = NULL,
  text_optional = NULL,
  text_padding = NULL,
  text_pitch_alignment = NULL,
  text_radial_offset = NULL,
  text_rotate = NULL,
  text_rotation_alignment = NULL,
  text_size = NULL,
  text_transform = NULL,
  text_translate = NULL,
  text_translate_anchor = NULL,
  text_variable_anchor = NULL,
  text_writing_mode = NULL,
  visibility = "visible",
  slot = NULL,
  min_zoom = NULL,
  max_zoom = NULL,
  popup = NULL,
  tooltip = NULL,
  hover_options = NULL,
  before_id = NULL,
  filter = NULL,
  cluster_options = NULL
)

Arguments

Value

The modified map object with the new symbol layer added.

Examples

## Not run: 
library(mapgl)
library(sf)
library(dplyr)

# Set seed for reproducibility
set.seed(1234)

# Define the bounding box for Washington DC (approximately)
bbox <- st_bbox(
    c(
        xmin = -77.119759,
        ymin = 38.791645,
        xmax = -76.909393,
        ymax = 38.995548
    ),
    crs = st_crs(4326)
)

# Generate 30 random points within the bounding box
random_points <- st_as_sf(
    data.frame(
        id = 1:30,
        lon = runif(30, bbox["xmin"], bbox["xmax"]),
        lat = runif(30, bbox["ymin"], bbox["ymax"])
    ),
    coords = c("lon", "lat"),
    crs = 4326
)

# Assign random icons
icons <- c("music", "bar", "theatre", "bicycle")
random_points <- random_points |>
    mutate(icon = sample(icons, n(), replace = TRUE))

# Map with icons
mapboxgl(style = mapbox_style("light")) |>
    fit_bounds(random_points, animate = FALSE) |>
    add_symbol_layer(
        id = "points-of-interest",
        source = random_points,
        icon_image = c("get", "icon"),
        icon_allow_overlap = TRUE,
        tooltip = "icon"
    )

## End(Not run)

Description

Adds an interactive time scrubber with a histogram to the map. The control filters temporal data by dragging a range across a bar chart. It can drive one or several layers at once — both flowmap layers and ordinary Mapbox/MapLibre layers (circle, fill, line, symbol, etc.) whose source features carry a time property.

Usage

add_time_control(
  map,
  data,
  time_column,
  layer_id = NULL,
  feature_time_property = NULL,
  feature_time_format = c("iso", "epoch_ms", "epoch_s"),
  time_interval = c("hour", "day"),
  position = "bottom-left",
  initial_range = NULL,
  loop = TRUE,
  speed = 500,
  autoplay = FALSE,
  accent_color = "#00bcd4",
  dark_mode = TRUE,
  draggable = TRUE,
  collapsible = FALSE,
  collapsed = FALSE,
  title = NULL
)

Arguments

Details

For ordinary layers, the control sets a Mapbox filter expression of the form ⁠[">=", ["get", feature_time_property], start] && ["<", ..., end]⁠. The property is assumed to be an ISO 8601 timestamp string by default; pass feature_time_format = "epoch_ms" (or "epoch_s") if your source data encodes time as numeric epoch milliseconds (or seconds).

For flowmap layers the control updates the selectedTimeRange of the flowmap filter via the flowmap.gl plugin.

Hold Shift while dragging on the histogram to add another selected time range. Multiple ranges are combined with OR semantics when filtering target layers.

Value

The modified map object.

Examples

# Create a flowmap centered on Montréal using the bundled datasets
maplibre(
  style = carto_style("dark-matter"),
  center = c(-73.58, 45.50),
  zoom = 11,
  projection = "mercator"
) |>
  add_flowmap(
    id = "bixi-rides",
    locations = bixi_locations,
    flows = bixi_flows,
    flow_time_column = "time",
    flow_color_scheme = "Teal",
    flow_dark_mode = TRUE
  ) |>
  add_time_control(
    data = bixi_flows,
    time_column = "time",
    time_interval = "hour",
    title = "BIXI Montréal Rides"
  )

Description

Add a vector tile source to a Mapbox GL or Maplibre GL map

Usage

add_vector_source(map, id, url = NULL, tiles = NULL, promote_id = NULL, ...)

Arguments

Value

The modified map object with the new source added.

Description

Add a video source to a Mapbox GL or Maplibre GL map

Usage

add_video_source(map, id, urls, coordinates)

Arguments

Value

The modified map object with the new source added.

Description

This function allows you to add additional data layers to existing maps created with mapboxgl_view() or maplibre_view(), enabling composition of multiple datasets on a single map.

Usage

add_view(
  map,
  data,
  color = "gold",
  column = NULL,
  n = NULL,
  palette = viridisLite::viridis,
  layer_id = NULL,
  legend = FALSE,
  legend_position = "bottom-left"
)

Arguments

Value

The map object with the new layer added

Examples

## Not run: 
library(sf)
nc <- st_read(system.file("shape/nc.shp", package = "sf"))

# Basic layering
mapboxgl_view(nc) |>
  add_view(nc[1:10, ], color = "red", layer_id = "subset")

# Layer different geometries
mapboxgl_view(polygons) |>
  add_view(points, color = "blue") |>
  add_view(lines, color = "green")

# Add raster data
mapboxgl_view(boundaries) |>
  add_view(elevation_raster, layer_id = "elevation")

## End(Not run)

Description

Creates a minimal map style with only a solid background color (or pattern) and no basemap tiles. Useful when you want to display data layers without any underlying map features.

Usage

basemap_style(color = "white", pattern = NULL)

Arguments

Value

A list representing a minimal map style, suitable for passing to the style parameter of maplibre() or mapboxgl().

Examples

## Not run: 
library(mapgl)

# Solid color background
maplibre(style = basemap_style("lightgrey")) |>
  add_fill_layer(
    id = "data",
    source = my_sf_data,
    fill_color = "steelblue"
  )

# Background pattern (image must be loaded with add_image())
maplibre(style = basemap_style(pattern = "parchment")) |>
  add_image("parchment", "parchment.jpg") |>
  add_line_layer(
    id = "borders",
    source = my_sf_data,
    line_color = "#2c1810"
  )

## End(Not run)

Description

Bivariate color palettes

Usage

bivariate_palettes(palette = NULL)

Arguments

Value

A named list of 3 by 3 color matrices, or one matrix if palette is provided.

Description

Create a bivariate color scale

Usage

bivariate_scale(
  data = NULL,
  x,
  y,
  x_values = NULL,
  y_values = NULL,
  x_breaks = NULL,
  y_breaks = NULL,
  method = "quantile",
  colors = NULL,
  palette = "blue_pink",
  na_color = "lightgrey"
)

Arguments

Value

A mapgl_bivariate_scale object.

Description

A dataset containing hourly aggregated bike sharing trips between BIXI stations in Montréal during the week of July 1 to July 7, 2019.

Usage

bixi_flows

Format

A data frame with 6,092 rows and 4 variables:

time

Hourly timestamp (POSIXct, UTC)

origin

Origin station ID (factor, matching bixi_locations$id)

dest

Destination station ID (factor, matching bixi_locations$id)

count

Aggregated number of bike sharing trips in that hour (integer)

Details

To minimize the package footprint, the dataset has been truncated to a minimum of three trips (retaining only flows where count > 2), which reduces the rows from 213,227 to 6,092, and compresses the final size to just ~22 KB.

Source

BIXI Montréal Open Data (https://bixi.com/fr/donnees-ouvertes). Prepared for https://github.com/FlowmapBlue/FlowmapBlue by Ilya Boyandin (https://twitter.com/ilyabo). Original interactive visualization on Flowmap.blue: https://www.flowmap.blue/1qTVOzkPB7U1ySI4g4uPtVBzzEDCI8n1WXAmQeZL15fE

See Also

bixi_locations

Examples

# Check first few records
print(head(bixi_flows))

Description

A dataset containing the names and coordinates of BIXI bicycle sharing stations in Montréal, Quebec, Canada.

Usage

bixi_locations

Format

A data frame with 618 rows and 4 variables:

id

Unique station ID (character, e.g., "4000", "MTL-ECO5.1-01")

name

Station name (character, e.g., "Jeanne-d'Arc / Ontario")

lat

Latitude coordinate (numeric)

lon

Longitude coordinate (numeric)

Source

BIXI Montréal Open Data (https://bixi.com/fr/donnees-ouvertes). Prepared for https://github.com/FlowmapBlue/FlowmapBlue by Ilya Boyandin (https://twitter.com/ilyabo).

See Also

bixi_flows

Examples

# Convert to sf object to view on a map
if (requireNamespace("sf", quietly = TRUE)) {
  bixi_sf <- sf::st_as_sf(bixi_locations, coords = c("lon", "lat"), crs = 4326)
  print(head(bixi_sf))
}

Description

Get CARTO Style URL

Usage

carto_style(style_name)

Arguments

Value

The style URL corresponding to the given style name.

Description

These functions extract different components from mapgl_classification objects (created by step_equal_interval(), step_quantile(), step_jenks()) and mapgl_continuous_scale objects (created by interpolate_palette()).

Usage

get_legend_labels(
  scale,
  format = "none",
  currency_symbol = "$",
  digits = 2,
  big_mark = ",",
  suffix = "",
  prefix = ""
)

get_legend_colors(scale)

get_breaks(scale)

## S3 method for class 'mapgl_classification'
print(x, format = "none", ...)

## S3 method for class 'mapgl_continuous_scale'
print(x, format = "none", ...)

Arguments

Value

get_legend_labels()

A character vector of formatted legend labels

get_legend_colors()

A character vector of colors

get_breaks()

A numeric vector of break values

Examples

## Not run: 
# Texas county income data
library(tidycensus)
tx <- get_acs(geography = "county", variables = "B19013_001",
              state = "TX", geometry = TRUE)

# Classification examples
eq_class <- step_equal_interval("estimate", tx$estimate, n = 4)
labels <- get_legend_labels(eq_class, format = "currency")
colors <- get_legend_colors(eq_class)
breaks <- get_breaks(eq_class)

# Continuous scale examples
scale <- interpolate_palette("estimate", tx$estimate, method = "quantile", n = 5)
labels <- get_legend_labels(scale, format = "compact", prefix = "$")
colors <- get_legend_colors(scale)

## End(Not run)

Description

This function allows you to remove specific controls or all controls from a map. You can target controls by their type names, which correspond to the function names used to add them (e.g., "navigation" for controls added with add_navigation_control).

Usage

clear_controls(map, controls = NULL)

Arguments