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 = NULL,
  popup_style = NULL,
  visibility = c("visible", "none"),
  before_id = NULL,
  slot = NULL
)

Arguments

map

A map object created by mapboxgl() or maplibre().

id

A unique layer ID.

locations

A data frame or sf point object with location data. Data frames must include id, lat, and lon columns. sf point objects must include id; coordinates are transformed to EPSG:4326 and serialized as lon/lat.

flows

A data frame with origin, dest, and count columns.

flow_color_scheme

FlowMapGL preset color scheme name, a character vector of at least two CSS colors, or a mapgl_continuous_scale object created by interpolate_palette(). Preset names are case-sensitive; use flowmap_color_schemes() to list them.

flow_opacity

Layer opacity between 0 and 1.

flow_dark_mode

Logical (TRUE or FALSE), or "auto"; whether to use FlowMapGL dark-mode colors. If "auto", the mode is dynamically detected based on the map style.

flow_blend

Logical (TRUE or FALSE), "auto", or a character string specifying a CSS mix-blend-mode.

Valid modes are: "normal", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn", "hard-light", "soft-light", "difference", "exclusion", "hue", "saturation", "color", and "luminosity".

Recommendations:

On dark basemaps: "screen" looks best, creating a glowing additive effect where flows overlap.
On light basemaps: "multiply" or "darken" looks best, increasing contrast against the light background.

If "auto", automatically chooses "screen" for dark styles and "multiply" for light styles. If before_id or slot is specified (interleaved mode), "auto" quietly disables blending (FALSE) without throwing a warning. If TRUE, defaults to "screen" when flow_dark_mode is TRUE, and "multiply" when FALSE. If FALSE, no blending is applied. Note: CSS blending requires a standalone canvas overlay and is ignored when before_id or slot is specified.

flow_fade_amount

Controls how much lower-magnitude flows fade compared to higher ones. Range: 0-100.

flow_highlight_color

Color used for highlighting hovered elements.

flow_locations_enabled

Whether to show location circles.

flow_location_totals_enabled

Whether to show incoming/outgoing totals as concentric circles at each location.

flow_location_labels_enabled

Whether to show text labels at locations.

flow_lines_rendering_mode

Controls how flow lines are rendered: "straight", "animated-straight", or "curved".

flow_line_thickness_scale

Multiplier for flow line thickness.

flow_line_curviness

Multiplier for flow line curviness (only used when flow_lines_rendering_mode is "curved").

flow_clustering_enabled

Whether to cluster nearby locations when zoomed out.

flow_clustering_auto

Whether to automatically adjust clustering level based on zoom.

flow_clustering_level

Fixed clustering zoom level. Only used when flow_clustering_auto is FALSE.

flow_fade_enabled

Whether to apply color fading to lower-magnitude flows.

flow_fade_opacity_enabled

Whether to also fade opacity for lower-magnitude flows.

flow_adaptive_scales_enabled

Whether to adapt flow thickness and color scales to the current viewport. This controls the spatial scale domain while panning and zooming.

flow_temporal_scale_domain

For temporal flowmaps, whether flow thickness and color scales use only the currently selected time range ("selected") or all flow data across the full time extent ("all").

flow_max_top_flows_display_num

Maximum number of flows to display.

flow_endpoints_in_viewport_mode

Controls when a flow is considered visible based on endpoint locations: "any" or "both".

flow_time_column

Optional column name in flows for time data.

flow_selected_time_range

Optional vector of two dates (or strings) for initial time filtering.

flow_selected_locations

Optional vector of location IDs to select.

flow_location_filter_mode

Optional location filter mode: "ALL", "INCOMING", "OUTGOING", or "BETWEEN".

tooltip

Hover tooltip content. Use FALSE/NULL to disable, TRUE for the default, a column name, a {brace} template, a concat()/number_format() expression, or a named list(location = , flow = ) to set different content for hovered locations vs flows. Available fields are, for locations: name, id, lat, lon, incoming, outgoing, internal (plus any locations columns); for flows: count, origin_id, origin_name, dest_id, dest_name (plus any flows columns).

popup

Click popup content. Same forms as tooltip; defaults to FALSE (disabled).

tooltip_style

Tooltip appearance. A preset string ("light", "dark", or "auto") or a tooltip_style() object (colors, border, radius, font, padding, shadow, and position = "floating"/"anchored"). Defaults to a light/dark preset matching flow_dark_mode.

popup_style

Popup appearance; same forms as tooltip_style.

visibility

Whether the layer is initially "visible" or "none".

before_id

Optional map layer ID to render before.

slot

Optional Mapbox Standard slot.

Value

The modified map object with the flowmap layer added.

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.

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
  )


# To animate the flows over time, pair the flowmap with a window-mode
# slider that targets the same layer id; see [add_slider_control()].