ggplot2::labs

Updated May 29, 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. Once the axis and legend labels are in place, you will typically want to add a descriptive title that tells the reader what the plot is about at a glance, and an optional subtitle that provides additional context without cluttering the main heading.

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. Below the main plot area, the bottom-right corner is the natural home for a caption — a short line of text that typically cites the data source, explains abbreviations, or adds a methodological note that supports the interpretation without distracting from the visual itself.

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)")

The caption field accepts a plain string and automatically positions the text in the lower-right corner of the plot. When you are composing a figure that will sit alongside other panels in a report or presentation, you can also add a small letter tag to the top-left corner so each subplot can be referenced by name in the surrounding text.

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. After you have added labels to a plot, you may encounter situations where you want to remove a label that was set earlier in a script, perhaps because you are reusing a ggplot object in a different context. Passing NULL to any labs() argument strips that label from the plot entirely.

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. For data frames with many columns, setting each label one by one through individual labs() arguments can become repetitive. The dictionary parameter accepts a named character vector that maps every column name to its display label in a single compact statement, which is especially handy when you reuse the same renaming scheme across several plots.

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. Beyond the visible text labels, labs() also provides arguments for adding alternative-text descriptions that screen readers and automated accessibility tools can surface. Setting alt and alt_insight makes your plots usable for a wider audience without altering the visual output.

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. While labs() is the modern, all-in-one interface for setting plot labels, you may encounter older code that uses the individual helper functions xlab(), ylab(), and ggtitle(). Understanding how these older functions map to labs() arguments helps when reading legacy scripts or when you need to set labels on a plot object that was created elsewhere.

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. Putting everything together, a complete publication-quality chart combines axis labels, a title, a subtitle, and a caption inside a single labs() call, often paired with a theme for polished typography. The following example shows a realistic end-to-end pattern that you can copy and adapt for your own plots.

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()

The example above applies all six label arguments in one call, which is the recommended pattern for any plot that will appear in a report, presentation, or publication. When you are assembling a figure that contains multiple separate plots — for instance, side-by-side comparisons — you can assign a distinct letter tag to each one so the reader can refer to individual panels in the surrounding prose.

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"))

labs() sets axis labels, title, subtitle, caption, and legend titles in one call. It is equivalent to calling xlab(), ylab(), and ggtitle() separately but more concise. Set a label to NULL to remove it entirely from the plot; setting it to "" keeps the space but shows no text.