Legends

In geoviz, a legend is automatically displayed as soon as you use tthe following thematic mapping functions: "viz_prop", "viz_choro", "viz_typo", "viz_propchoro", "viz_proptypo", "viz_picto", "viz_gridprop", "viz_gridchoro", "viz_smooth" and "viz_dotdensity".

Under the hood, these functions actually call legend functions that can also be used separately. For example, the viz_prop function calls viz_leg_circles. The viz_choro function calls viz_leg_choro_vertical. The viz_typo function calls viz_leg_typo_vertical, and so on.

Consequently, to understand how to configure legends, refer to the documentation of the legend functions.

You can use legend functions directly.

bks <- c(200, 1000, 5000, 10000, 50000, 200000)
cols <- c('#fee5d9','#fcae91','#fb6a4a','#de2d26','#a50f15')

viz_create(projection = "EqualEarth", zoomable = T) |>
viz_path(data = world, fill = "#CCC") |>
viz_leg_choro_vertical(pos = c(10, 50), breaks = bks,
                       colors = cols, title = "Population" ) |>
viz_render()

Or use them directly through the thematic mapping functions, with the leg_ prefix.

viz_create(projection = "EqualEarth", zoomable = T) |>
viz_choro(data = world, var = "gdppc", breaks = bks, colors = cols,
          leg_pos = c(10,50), leg_title = "Population") |>
viz_render()

Positioning

The legend is positioned by default in the top-left corner of the page. However, you can specify exactly where you want to place it using the pos parameter. The position is always defined in SVG coordinates (not geographic ones).

viz_create(projection = "EqualEarth", zoomable = T) |>
viz_path(data = world, fill = "#CCC") |>
  viz_leg_choro_vertical(pos = c(420, 250)) |>
  viz_render()

If you really want to control the exact position of the legend, it is recommended to set the map width using the width parameter. The width defines the map’s coordinate system, but not necessarily its displayed size (because the param responsive is TRUE in the viz_create function). However, it allows you to position the legend accurately.

viz_create(projection = "EqualEarth", zoomable = T, width = 1000) |>
viz_path(data = world, fill = "#CCC") |>
  viz_leg_choro_vertical(pos = c(420, 250)) |>
  viz_render()

In this case, the size of the legend change since it depends on the size of the SVG document.

Main features

All legends share common useful parameters. First, the legend parameter (logical) allows you to show or hide the legend. Then, you can add a title (leg_title), a subtitle (leg_subtitle), and a note (leg_note).

viz_create(projection = "EqualEarth", zoomable = T) |>
viz_choro(data = world, var = "gdppc", breaks = bks, colors = cols,
          leg_pos = c(10,50), leg_title = "Population",
          leg_subtitle = "in 2020", leg_note = "mad with geoviz") |>
viz_render()

There is also often a leg_type parameter that lets you choose the desired type of legend.

viz_create(projection = "EqualEarth", zoomable = T) |>
viz_choro(data = world, var = "gdppc", breaks = bks,
          colors = cols, opacity = 0.1,
          leg_pos = c(10,50), leg_title = "Population",
          leg_subtitle = "in 2020", leg_note = "mad with geoviz",
          leg_type = "horizontal") |>
viz_render()

Styling

Frame

You can add a frame around the legend, including a background, using the frame (or leg_frame) parameter. This frame is fully customizable. You can change margins, background color, border, and more.

viz_create(projection = "EqualEarth", zoomable = T) |>
viz_typo(data = world, var = "region", leg_pos = c(30,30), 
           leg_frame = TRUE, leg_frame_margin = 20, 
           leg_frame_fill = "yellow", leg_frame_fillOpacity = 0.3, 
           leg_frame_stroke = "red", leg_frame_strokeWidth = 2) |>
viz_render()

Values

With the values or leg_values prefix, you can modify everything related to legend values: rounding them, repositioning them, or changing their colors. You can use any SVG attributes, even those that are not listed in the documentation.

viz_create(projection = "EqualEarth", zoomable = T) |>
viz_path(data = world, fill = "#CCC") |>
viz_prop(data = world, fill = "#4a4a4a", fillOpacity = 0.3, var = "pop",
         leg_values_round = 0,  leg_values_factor = 1/1000000,
         leg_values_dx = 20, leg_values_fill = "red",
         leg_values_fontSize = 30, leg_values_thousands = ",",) |>
viz_render()

Boxes

Following the same logic, you can modify the appearance and size of legend boxes.

viz_create(projection = "EqualEarth", zoomable = T) |>
viz_choro(data = world, var = "gdppc", leg_rect_width = 10,
            leg_rect_height = 30, leg_rect_spacing = 10,
            leg_rect_strokeWidth =1, leg_rect_stroke = "red") |>
viz_render()

Circles, lines, and so on…

This logic applies to all legend elements (circles, squares, etc.).

viz_create(projection = "EqualEarth", zoomable = T) |>
  viz_path(data = world, fill = "#CCC") |>
  viz_prop(data = world, fill = "#4a4a4a", fillOpacity = 0.3,  var = "gdp",
           leg_circle_fill = "#38896F", leg_line_length = 100 ) |>
  viz_render()

In this way, you can build fully customized legends.

viz_create(projection = "EqualEarth", zoomable = T) |>
viz_path(data = world, fill = "#CCC") |>
viz_leg_circles_nested( nb = 6, gap = 5, title = "Population",
                        subtitle = "In inh.", circle_fill = "#38896F",
                        circle_fillOpacity = 0.5, circle_stroke = "white",
                        line_stroke = "#38896F", line_width = 50,
                        line_length = 80, values_dy = -5, values_round = 0,
                        values_textAnchor = "end", values_fill = "#38896F",
                        note = "Made with Geoviz", note_dy = 5) |>
viz_render()

Refer to the documentation to see what you can modify.

Nicolas Lambert

2026-05-04

Positioning

Main features

Styling