Getting Started with ggguides

Installation

install.packages("ggguides")

Or the development version from GitHub:

# install.packages("pak")
pak::pak("gcol33/ggguides")

Overview

ggguides simplifies common legend operations in ggplot2. Instead of memorizing theme element names and their nested structure, you can use intuitive one-liner functions to position, style, and manage legends.

Key features:

  • Position legends with legend_left(), legend_right(), legend_top(), legend_bottom(), legend_inside()

  • Style legends with legend_style() for fonts, backgrounds, and borders

  • Wrap legend entries with legend_wrap() for multi-column layouts

  • Collect legends from patchwork compositions with collect_legends()

Basic Usage

Let’s create a simple plot to demonstrate the legend helpers:

p <- ggplot(mtcars, aes(mpg, wt, color = factor(cyl))) +
  geom_point(size = 3) +
  labs(color = "Cylinders")

p

Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with the cylinders legend on the right.

Moving the Legend

Position the legend on any side with a single function call:

p + legend_left()

Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with the legend on the left of the panel.

p + legend_bottom()

Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with the legend below the panel and its keys in a row.

Inside Positioning

Place the legend inside the plot area using coordinates or shortcuts:

p + legend_inside(position = "topright")

Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with the legend inside the panel in the top-right corner.

p + legend_inside(x = 0.02, y = 0.98, justification = c("left", "top"))

Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with the legend inside the panel in the top-left corner.

Removing the Legend

p + legend_none()

Scatter plot of car weight against fuel economy, points coloured by number of cylinders, without a legend.

Styling Legends

Use legend_style() to customize the legend appearance:

p + legend_style(size = 18)

Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with the legend title and labels drawn larger.

p + legend_style(
  size = 15,
  title_size = 20,
  title_face = "bold",
  background = "#FFF3E0",
  background_color = "#FF9800"
)

Scatter plot of car weight against fuel economy, points coloured by number of cylinders, with a bold legend title and the legend on a cream box with an orange border.

Wrapping Legend Entries

For legends with many entries, use legend_wrap() to create multi-column layouts:

ggplot(mpg, aes(displ, hwy, color = class)) +
  geom_point() +
  legend_wrap(ncol = 2)

Scatter plot of highway mileage against engine displacement, points coloured by the seven car classes, with the legend keys in two columns on the right.

Combining Functions

ggguides functions compose naturally with the + operator:

ggplot(mpg, aes(displ, hwy, color = class)) +
  geom_point() +
  legend_left() +
  legend_style(size = 15, title_face = "bold", background = "#FFF3E0")

Scatter plot of highway mileage against engine displacement, points coloured by the seven car classes, with the legend on the left on a cream box, its title in bold.

ggplot(mpg, aes(displ, hwy, color = class)) +
  geom_point() +
  legend_wrap(ncol = 2) +
  legend_bottom()

Scatter plot of highway mileage against engine displacement, points coloured by the seven car classes, with the legend below the panel and its keys in two columns.

What’s Next