Guide primitive: title

This function constructs a title guide primitive.

Usage

primitive_title(
  title = waiver(),
  angle = waiver(),
  theme = NULL,
  position = waiver()
)

Arguments

title

One of the following to indicate the title of the guide:

• A <character[1]> or <expression[1]> to set a custom title.

• NULL to not display any title.

• waiver() (default) to take the name of the scale object or the name specified in labs() as the title.

angle

A specification for the text angle. Compared to setting the angle argument in element_text(), this argument uses some heuristics to automatically pick the hjust and vjust that you probably want. Can be one of the following:

• NULL to take angles and justification settings directly from the theme.

• waiver() to allow reasonable defaults in special cases.

• A <numeric[1]> between -360 and 360 for the text angle in degrees.

theme

A <theme> object to style the guide individually or differently from the plot's theme settings. The theme argument in the guide overrides and is combined with the plot's theme.

position

A <character[1]> giving the location of the guide. Can be one of "top", "bottom", "left" or "right".

Value

A <PrimitiveTitle> primitive guide that can be used inside other guides.

Styling options

Below are the theme options that determine the styling of this guide, which may differ depending on whether the guide is used in an axis or in a legend context.

As an axis guide

• axis.title.{x/y}.{position} an <element_text> for the title display.

As a legend guide

• legend.title an <element_text> for the title display.

See also

Other primitives: primitive_box(), primitive_bracket(), primitive_fence(), primitive_labels(), primitive_line(), primitive_segments(), primitive_spacer(), primitive_ticks()

Examples

# A standard plot
p <- ggplot(mpg, aes(displ, hwy)) +
 geom_point()

# Adding as secondary guides
p + guides(
  x.sec = primitive_title("Horizontal Title"),
  y.sec = primitive_title(c("along vertical", "Multiple tiles"))
)


# 'Real' titles occur once per plot.
# Primitive titles repeat over facets and hide the 'real' title.
p + facet_wrap(~ drv) +
  guides(x = primitive_title("I am a repeated subtitle")) +
  labs(x = "I am the hidden real title")