R Mapgl

mapgl: Interactive WebGL Maps in R

Overview

mapgl wraps Mapbox GL JS and MapLibre GL JS for interactive WebGL maps in R. Data goes on a map as a source and is drawn by a layer. Typical pipe: maplibre() or mapboxgl() -> add_*_layer(); style with interpolate() / match_expr() / step_expr(); update reactively in Shiny with maplibre_proxy().

References

Read references/API.md before writing code.

• references/API.md -- Complete function reference (every add_*, set_*, turf_*, expression helper, legend, Shiny output).
• references/getting-started.md -- Vignette: Mapbox vs MapLibre, styles, tokens, *_view().
• references/layers-overview.md -- Vignette: every layer type with full worked examples.
• references/shiny.md -- Vignette: proxies, reactive map inputs, compare widgets.
• references/story-maps.md -- Vignette: scrollytelling with story_map() / on_section().
• references/turf.md -- Vignette: client-side spatial ops (buffer, filter, intersect).

When NOT to Use

• Simple marker maps with <1k points -- leaflet is lighter.
• Static print maps -- tmap or ggplot2 + sf.
• Non-spatial plots -- ggplot2.
• Datasets >100k features -- tile first with freestiler, then add_pmtiles_source().

API Keys

• maplibre() + carto_style() / openfreemap_style() -- no key. Default style is carto_style("voyager").
• mapboxgl() / mapbox_style() -- set MAPBOX_PUBLIC_TOKEN in .Renviron.
• maptiler_style() -- set MAPTILER_API_KEY.

Quick Reference

Create a map

Layers

All take map, id, source, source_layer (opt, for vector/PMTiles), popup (opt), tooltip (opt), hover_options (opt), filter (opt), before_id (opt), min_zoom/max_zoom (opt).

Sources

promote_id is required on vector / PMTiles sources that need hover or feature_click.

Styling expressions (data-driven styling)

Camera, controls, legends

• Camera: fit_bounds(map, bbox, animate=FALSE), fly_to(map, center, zoom), ease_to(), jump_to(), set_view().
• Controls: add_navigation_control(), add_fullscreen_control(), add_scale_control(), add_geolocate_control(), add_layers_control(layers=NULL, collapsible=TRUE), add_draw_control(rectangle=FALSE, show_measurements=FALSE), add_geocoder_control().
• Legends: add_legend(legend_title, values, colors, type=c("continuous","categorical"), patch_shape="square", position="top-left", add=FALSE, layer_id=NULL, interactive=FALSE). Also add_categorical_legend(), add_continuous_legend(), clear_legend().

Shiny

• Output / render: maplibreOutput("map", height="600px") + renderMaplibre({...}). Same for mapboxgl.
• Proxy (mutate without re-render): maplibre_proxy("map") / mapboxgl_proxy("map") inside observeEvent().
• Proxy-compatible: set_filter(), set_paint_property(), set_layout_property(), set_style(), clear_layer(), add_*_layer(), fly_to(), fit_bounds(), add_markers().
• Auto inputs: input$<mapId>_click, ..._feature_click, ..._zoom, ..._center, ..._bbox, ..._drawn_features.
• Compare widget: compare(m1, m2, mode="swipe"|"sync"); Shiny: maplibreCompareOutput() + maplibre_compare_proxy(map_side="before"|"after").

Story maps & turf.js

• Story: story_map() / story_maplibre() UI + story_section(title, content, position="left") + server on_section(map_id, section_id, expr).
• Client-side spatial: turf_buffer(), turf_filter(predicate="intersects"|"within"|"contains"|"crosses"|"disjoint"), turf_intersect(), turf_union(), turf_difference(), turf_convex_hull(), turf_concave_hull(), turf_voronoi(), turf_centroid().

Quick Start

library(mapgl); library(sf)
nc <- st_read(system.file("shape/nc.shp", package = "sf"))

maplibre(style = carto_style("positron"), bounds = nc) |>
  add_fill_layer(
    id = "counties",
    source = nc,
    fill_color = interpolate(
      column = "BIR74",
      values = c(500, 20000),
      stops = c("#eff3ff", "#08519c"),
      na_color = "lightgrey"
    ),
    fill_opacity = 0.7,
    popup = "NAME",
    hover_options = list(fill_color = "yellow")
  ) |>
  add_legend("Births (1974)",
             values = c(500, 20000),
             colors = c("#eff3ff", "#08519c"))

Shiny pattern (proxy, not re-render)

library(shiny); library(mapgl)
ui <- fluidPage(sliderInput("min", "Min BIR74", 0, 22000, 500),
                maplibreOutput("map", height = "600px"))
server <- function(input, output, session) {
  output$map <- renderMaplibre({
    maplibre(carto_style("positron"), bounds = nc) |>
      add_fill_layer(id = "ct", source = nc, fill_color = "steelblue")
  })
  observeEvent(input$min, {
    maplibre_proxy("map") |>
      set_filter("ct", list(">=", get_column("BIR74"), input$min))
  })
}

PMTiles pattern (large data)

maplibre() |>
  add_pmtiles_source(id = "src", url = "https://example.com/data.pmtiles") |>
  add_fill_layer(id = "pm", source = "src",
                 source_layer = "features",  # must match freestiler layer_name
                 fill_color = "steelblue")

Common Mistakes

Resources

Package site | GitHub | Sibling skills r-freestiler (tiles) and r-mapping (chooser).