Skip to contents

This axis allows a greater degree of control than the default axes guides. In particular, this axis allows setting break positions and labels independently from the scale and is not bound by the same constraints as secondary axes. Additionally, label attributes may be set in parallel to the labels themselves, circumventing the unsupported vectorised input to element_text().


  title = waiver(),
  breaks = waiver(),
  labels = waiver(),
  label_family = NULL,
  label_face = NULL,
  label_colour = NULL,
  label_size = NULL,
  label_hjust = NULL,
  label_vjust = NULL,
  label_lineheight = NULL,
  label_color = NULL,
  label_margin = NULL,
  check.overlap = FALSE,
  angle = NULL, = 1,
  order = 0,
  colour = NULL,
  color = NULL,
  trunc_lower = NULL,
  trunc_upper = NULL,
  position = waiver()



A character string or expression indicating a title of guide. If NULL, the title is not shown. By default (waiver()), the name of the scale object or the name specified in labs() is used for the title.


One of the following ways to parametrise the tick and label positions:

  • NULL to draw no ticks and labels.

  • waiver() for the default breaks computed by the scale (default).

  • A numeric vector for continuous or discrete scales, or a character vector for discrete scales.

  • A function that takes the limits as input and returns breaks as output. Also accepts rlang lambda notation.

  • A unit vector for setting data-independent breaks.


One of the following ways to dictate the labels:

  • NULL to draw no labels.

  • waiver() for the default labels computed by the scale on the breaks (default). Note that a scale with non-identity transformation is unlikely to graciously handle breaks defined in grid-units.

  • A character vector giving

  • A function that takes the breaks as input and returns labels as output. Also accepts rlang lambda notation.

label_family, label_face, label_colour, label_size, label_hjust, label_vjust, label_lineheight, label_color, label_margin

Arguments passed down to the label constructor. See element_text() arguments, which these arguments mirror with the label_-prefix. With the exception of label_margin, the other label_* arguments are assumed be parallel to (the result of) the labels argument and will be recycled with rep_len() as necessary. By default, these parameters are taken from the theme.


silently remove overlapping labels, (recursively) prioritizing the first, last, and middle labels.


Compared to setting the angle in theme() / element_text(), this also uses some heuristics to automatically pick the hjust and vjust that you probably want.

The number of rows (for vertical axes) or columns (for horizontal axes) that should be used to render the labels. This is useful for displaying labels that would otherwise overlap.


Used to determine the order of the guides (left-to-right, top-to-bottom), if more than one guide must be drawn at the same location.

colour, color

A character(1) with a valid colour for colouring the axis text, axis ticks and axis line. Overrules the colour assigned by the theme.

trunc_lower, trunc_upper

The lower and upper range of the truncated axis:

  • NULL to not perform any truncation.

  • A function that takes the break positions as input and returns the lower or upper boundary. Note that also for discrete scales, positions are the mapped positions as numeric.

  • A numeric value in data units for the lower and upper boundaries.

  • A unit object.


Where this guide should be drawn: one of top, bottom, left, or right.


An axis_manual guide class object.


ggplot(iris, aes(Species, Sepal.Width)) +
  geom_boxplot(aes(fill = Species)) +
  guides(x = guide_axis_manual(
    label_colour = scales::hue_pal()(3),
    label_face = c("bold", "italic", "plain"),
    labels = toupper

# Using the manual axis to annotate some specific point
ggplot(pressure, aes(temperature, pressure)) +
  geom_point() +
  geom_hline(yintercept = 300, linetype = 2, colour = "blue") +
  guides(y.sec = guide_axis_manual(breaks = 300, labels = "some\nthreshold",
                                   label_colour = "blue"))