ggplot2::labs

Updated May 20, 2026· Tidyverse

ggplot2labelstitlecaptiontidyverser

labs() sets all text elements of a plot — axis labels, legend title, title, subtitle, caption, and tag — in one call. It replaces the older xlab(), ylab(), and ggtitle() functions which are now superseded.

Signature

labs(..., title = NULL, subtitle = NULL, caption = NULL, tag = NULL)

Parameters:

... — name-value pairs where name is an aesthetic (e.g., colour, fill, size)
title — plot title (top-left)
subtitle — subtitle below the title
caption — bottom-right, often data source or notes
tag — top-left tag for subplot labelling (e.g., “A”, “B”)

Returns: A ggplot object (for chaining).

Values can be a string, a function formatter, NULL to remove, or waiver() to use the default.

Setting Axis and Legend Labels

Set axis labels directly by aesthetic name:

library(ggplot2)

p <- ggplot(mtcars, aes(mpg, wt, colour = factor(cyl)) +
  geom_point()

p + labs(x = "Weight (1000 lbs)", y = "Miles per gallon", colour = "Cylinders")

The colour argument sets the legend title for the colour aesthetic.

Setting the Plot Title and Subtitle

p + labs(
  title = "Fuel Efficiency by Vehicle Weight",
  subtitle = "Data from the 1973 Motor Trend magazine survey"
)

The title appears at the top-left of the plot. The subtitle appears directly below it in smaller text.

Adding a Caption

Captions go in the bottom-right and are commonly used for data sources or notes:

p + labs(caption = "Source: mtcars dataset (1973 Motor Trend)")

Using a Tag for Subplots

Tags label individual subplots, typically with a letter:

p + labs(title = "Fuel Efficiency", tag = "A")

Use tag when combining multiple plots with patchwork or cowplot to label each panel.

Removing Labels

Set a label to NULL to remove it:

p + labs(title = NULL)      # removes the title
p + labs(subtitle = NULL)   # removes the subtitle
p + labs(caption = NULL)    # removes the caption

If a plot already has a label set and you want to remove it, pass NULL to that argument.

Using a Dictionary for Multiple Labels

The dictionary argument maps variable names to labels across the plot:

p + labs(dictionary = c(
  disp = "Displacement (cu in)",
  cyl  = "Number of cylinders",
  mpg  = "Miles per gallon",
  wt   = "Weight (1000 lbs)"
))

This is useful when you want consistent label renaming without setting each scale individually.

Setting Alt Text for Accessibility

Use alt and alt_insight for automated alt text generation:

p + labs(
  alt = "Scatter plot showing fuel efficiency vs weight, coloured by cylinder count",
  alt_insight = "The plot shows a clear negative relationship: heavier vehicles have lower fuel efficiency."
)

alt can also be a function that receives the plot and returns text.

Relationship to Individual Scale Functions

You can set labels in individual scales, but labs() covers all of them at once:

# These three:
p + labs(x = "Weight", colour = "Cylinders", title = "My Title")

# Are equivalent to setting each scale separately:
p + xlab("Weight") + labs(colour = "Cylinders") + ggtitle("My Title")

labs() is preferred because it keeps all label changes in one place.

Common Use Cases

Publication-Ready Charts

ggplot(mtcars, aes(wt, mpg, colour = factor(cyl)) +
  geom_point(size = 3) +
  labs(
    title    = "Vehicle Weight vs Fuel Efficiency",
    subtitle = "Negative relationship across all cylinder counts",
    caption  = "Source: 1973 Motor Trend magazine",
    x        = "Weight (1000 lbs)",
    y        = "Miles per gallon",
    colour   = "Cylinders"
  ) +
  theme_minimal()

Multi-Plot Labelling

p1 <- ggplot(mtcars, aes(mpg, wt)) + geom_point()
p2 <- ggplot(mtcars, aes(mpg, hp)) + geom_point()

(p1 + labs(tag = "A")) + (p2 + labs(tag = "B"))