% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/theme.R
\name{theme}
\alias{theme}
\title{Modify components of a theme}
\usage{
theme(
  ...,
  line,
  rect,
  text,
  title,
  point,
  polygon,
  geom,
  spacing,
  margins,
  aspect.ratio,
  axis.title,
  axis.title.x,
  axis.title.x.top,
  axis.title.x.bottom,
  axis.title.y,
  axis.title.y.left,
  axis.title.y.right,
  axis.text,
  axis.text.x,
  axis.text.x.top,
  axis.text.x.bottom,
  axis.text.y,
  axis.text.y.left,
  axis.text.y.right,
  axis.text.theta,
  axis.text.r,
  axis.ticks,
  axis.ticks.x,
  axis.ticks.x.top,
  axis.ticks.x.bottom,
  axis.ticks.y,
  axis.ticks.y.left,
  axis.ticks.y.right,
  axis.ticks.theta,
  axis.ticks.r,
  axis.minor.ticks.x.top,
  axis.minor.ticks.x.bottom,
  axis.minor.ticks.y.left,
  axis.minor.ticks.y.right,
  axis.minor.ticks.theta,
  axis.minor.ticks.r,
  axis.ticks.length,
  axis.ticks.length.x,
  axis.ticks.length.x.top,
  axis.ticks.length.x.bottom,
  axis.ticks.length.y,
  axis.ticks.length.y.left,
  axis.ticks.length.y.right,
  axis.ticks.length.theta,
  axis.ticks.length.r,
  axis.minor.ticks.length,
  axis.minor.ticks.length.x,
  axis.minor.ticks.length.x.top,
  axis.minor.ticks.length.x.bottom,
  axis.minor.ticks.length.y,
  axis.minor.ticks.length.y.left,
  axis.minor.ticks.length.y.right,
  axis.minor.ticks.length.theta,
  axis.minor.ticks.length.r,
  axis.line,
  axis.line.x,
  axis.line.x.top,
  axis.line.x.bottom,
  axis.line.y,
  axis.line.y.left,
  axis.line.y.right,
  axis.line.theta,
  axis.line.r,
  legend.background,
  legend.margin,
  legend.spacing,
  legend.spacing.x,
  legend.spacing.y,
  legend.key,
  legend.key.size,
  legend.key.height,
  legend.key.width,
  legend.key.spacing,
  legend.key.spacing.x,
  legend.key.spacing.y,
  legend.key.justification,
  legend.frame,
  legend.ticks,
  legend.ticks.length,
  legend.axis.line,
  legend.text,
  legend.text.position,
  legend.title,
  legend.title.position,
  legend.position,
  legend.position.inside,
  legend.direction,
  legend.byrow,
  legend.justification,
  legend.justification.top,
  legend.justification.bottom,
  legend.justification.left,
  legend.justification.right,
  legend.justification.inside,
  legend.location,
  legend.box,
  legend.box.just,
  legend.box.margin,
  legend.box.background,
  legend.box.spacing,
  panel.background,
  panel.border,
  panel.spacing,
  panel.spacing.x,
  panel.spacing.y,
  panel.grid,
  panel.grid.major,
  panel.grid.minor,
  panel.grid.major.x,
  panel.grid.major.y,
  panel.grid.minor.x,
  panel.grid.minor.y,
  panel.ontop,
  panel.widths,
  panel.heights,
  plot.background,
  plot.title,
  plot.title.position,
  plot.subtitle,
  plot.caption,
  plot.caption.position,
  plot.tag,
  plot.tag.position,
  plot.tag.location,
  plot.margin,
  strip.background,
  strip.background.x,
  strip.background.y,
  strip.clip,
  strip.placement,
  strip.text,
  strip.text.x,
  strip.text.x.bottom,
  strip.text.x.top,
  strip.text.y,
  strip.text.y.left,
  strip.text.y.right,
  strip.switch.pad.grid,
  strip.switch.pad.wrap,
  complete = FALSE,
  validate = TRUE
)
}
\arguments{
\item{...}{additional element specifications not part of base ggplot2. In general,
these should also be defined in the \verb{element tree} argument. \link[rlang:splice]{Splicing} a list is also supported.}

\item{line}{all line elements (\code{\link[=element_line]{element_line()}})}

\item{rect}{all rectangular elements (\code{\link[=element_rect]{element_rect()}})}

\item{text}{all text elements (\code{\link[=element_text]{element_text()}})}

\item{title}{all title elements: plot, axes, legends (\code{\link[=element_text]{element_text()}};
inherits from \code{text})}

\item{point}{all point elements (\code{\link[=element_point]{element_point()}})}

\item{polygon}{all polygon elements (\code{\link[=element_polygon]{element_polygon()}})}

\item{geom}{defaults for geoms (\code{\link[=element_geom]{element_geom()}})}

\item{spacing}{all spacings (\code{\link[grid:unit]{unit()}})}

\item{margins}{all margins (\code{\link[=margin]{margin()}})}

\item{aspect.ratio}{aspect ratio of the panel}

\item{axis.title, axis.title.x, axis.title.y, axis.title.x.top, axis.title.x.bottom, axis.title.y.left, axis.title.y.right}{labels of axes (\code{\link[=element_text]{element_text()}}). Specify all axes' labels (\code{axis.title}),
labels by plane (using \code{axis.title.x} or \code{axis.title.y}), or individually
for each axis (using \code{axis.title.x.bottom}, \code{axis.title.x.top},
\code{axis.title.y.left}, \code{axis.title.y.right}). \verb{axis.title.*.*} inherits from
\verb{axis.title.*} which inherits from \code{axis.title}, which in turn inherits
from \code{text}}

\item{axis.text, axis.text.x, axis.text.y, axis.text.x.top, axis.text.x.bottom, axis.text.y.left, axis.text.y.right, axis.text.theta, axis.text.r}{tick labels along axes (\code{\link[=element_text]{element_text()}}). Specify all axis tick labels (\code{axis.text}),
tick labels by plane (using \code{axis.text.x} or \code{axis.text.y}), or individually
for each axis (using \code{axis.text.x.bottom}, \code{axis.text.x.top},
\code{axis.text.y.left}, \code{axis.text.y.right}). \verb{axis.text.*.*} inherits from
\verb{axis.text.*} which inherits from \code{axis.text}, which in turn inherits
from \code{text}}

\item{axis.ticks, axis.ticks.x, axis.ticks.x.top, axis.ticks.x.bottom, axis.ticks.y, axis.ticks.y.left, axis.ticks.y.right, axis.ticks.theta, axis.ticks.r}{tick marks along axes (\code{\link[=element_line]{element_line()}}). Specify all tick marks (\code{axis.ticks}),
ticks by plane (using \code{axis.ticks.x} or \code{axis.ticks.y}), or individually
for each axis (using \code{axis.ticks.x.bottom}, \code{axis.ticks.x.top},
\code{axis.ticks.y.left}, \code{axis.ticks.y.right}). \verb{axis.ticks.*.*} inherits from
\verb{axis.ticks.*} which inherits from \code{axis.ticks}, which in turn inherits
from \code{line}}

\item{axis.minor.ticks.x.top, axis.minor.ticks.x.bottom, axis.minor.ticks.y.left, axis.minor.ticks.y.right, axis.minor.ticks.theta, axis.minor.ticks.r, }{minor tick marks along axes (\code{\link[=element_line]{element_line()}}). \verb{axis.minor.ticks.*.*}
inherit from the corresponding major ticks \verb{axis.ticks.*.*}.}

\item{axis.ticks.length, axis.ticks.length.x, axis.ticks.length.x.top, axis.ticks.length.x.bottom, axis.ticks.length.y, axis.ticks.length.y.left, axis.ticks.length.y.right, axis.ticks.length.theta, axis.ticks.length.r}{length of tick marks (\code{unit}). \code{axis.ticks.length} inherits from \code{spacing}.}

\item{axis.minor.ticks.length, axis.minor.ticks.length.x, axis.minor.ticks.length.x.top, axis.minor.ticks.length.x.bottom, axis.minor.ticks.length.y, axis.minor.ticks.length.y.left, axis.minor.ticks.length.y.right, axis.minor.ticks.length.theta, axis.minor.ticks.length.r}{length of minor tick marks (\code{unit}), or relative to \code{axis.ticks.length} when provided with \code{rel()}.}

\item{axis.line, axis.line.x, axis.line.x.top, axis.line.x.bottom, axis.line.y, axis.line.y.left, axis.line.y.right, axis.line.theta, axis.line.r}{lines along axes (\code{\link[=element_line]{element_line()}}). Specify lines along all axes (\code{axis.line}),
lines for each plane (using \code{axis.line.x} or \code{axis.line.y}), or individually
for each axis (using \code{axis.line.x.bottom}, \code{axis.line.x.top},
\code{axis.line.y.left}, \code{axis.line.y.right}). \verb{axis.line.*.*} inherits from
\verb{axis.line.*} which inherits from \code{axis.line}, which in turn inherits
from \code{line}}

\item{legend.background}{background of legend (\code{\link[=element_rect]{element_rect()}}; inherits
from \code{rect})}

\item{legend.margin}{the margin around each legend (\code{\link[=margin]{margin()}}); inherits
from \code{margins}.}

\item{legend.spacing, legend.spacing.x, legend.spacing.y}{the spacing between legends (\code{unit}). \code{legend.spacing.x} & \code{legend.spacing.y}
inherit from \code{legend.spacing} or can be specified separately.
\code{legend.spacing} inherits from \code{spacing}.}

\item{legend.key}{background underneath legend keys (\code{\link[=element_rect]{element_rect()}};
inherits from \code{rect})}

\item{legend.key.size, legend.key.height, legend.key.width}{size of legend keys (\code{unit}); key background height & width inherit from
\code{legend.key.size} or can be specified separately. In turn \code{legend.key.size}
inherits from \code{spacing}.}

\item{legend.key.spacing, legend.key.spacing.x, legend.key.spacing.y}{spacing
between legend keys given as a \code{unit}. Spacing in the horizontal (x) and
vertical (y) direction inherit from \code{legend.key.spacing} or can be
specified separately. \code{legend.key.spacing} inherits from \code{spacing}.}

\item{legend.key.justification}{Justification for positioning legend keys
when more space is available than needed for display. The default, \code{NULL},
stretches keys into the available space. Can be a location like \code{"center"}
or \code{"top"}, or a two-element numeric vector.}

\item{legend.frame}{frame drawn around the bar (\code{\link[=element_rect]{element_rect()}}).}

\item{legend.ticks}{tick marks shown along bars or axes (\code{\link[=element_line]{element_line()}})}

\item{legend.ticks.length}{length of tick marks in legend
(\code{\link[grid:unit]{unit()}}); inherits from \code{legend.key.size}.}

\item{legend.axis.line}{lines along axes in legends (\code{\link[=element_line]{element_line()}})}

\item{legend.text}{legend item labels (\code{\link[=element_text]{element_text()}}; inherits from
\code{text})}

\item{legend.text.position}{placement of legend text relative to legend keys
or bars ("top", "right", "bottom" or "left"). The legend text placement
might be incompatible with the legend's direction for some guides.}

\item{legend.title}{title of legend (\code{\link[=element_text]{element_text()}}; inherits from
\code{title})}

\item{legend.title.position}{placement of legend title relative to the main
legend ("top", "right", "bottom" or "left").}

\item{legend.position}{the default position of legends ("none", "left",
"right", "bottom", "top", "inside")}

\item{legend.position.inside}{A numeric vector of length two setting the
placement of legends that have the \code{"inside"} position.}

\item{legend.direction}{layout of items in legends ("horizontal" or
"vertical")}

\item{legend.byrow}{whether the legend-matrix is filled by columns
(\code{FALSE}, the default) or by rows (\code{TRUE}).}

\item{legend.justification}{anchor point for positioning legend inside plot
("center" or two-element numeric vector) or the justification according to
the plot area when positioned outside the plot}

\item{legend.justification.top, legend.justification.bottom, legend.justification.left, legend.justification.right, legend.justification.inside}{Same as \code{legend.justification} but specified per \code{legend.position} option.}

\item{legend.location}{Relative placement of legends outside the plot as a
string. Can be \code{"panel"} (default) to align legends to the panels or
\code{"plot"} to align legends to the plot as a whole.}

\item{legend.box}{arrangement of multiple legends ("horizontal" or
"vertical")}

\item{legend.box.just}{justification of each legend within the overall
bounding box, when there are multiple legends ("top", "bottom", "left",
"right", "center" or "centre")}

\item{legend.box.margin}{margins around the full legend area, as specified
using \code{\link[=margin]{margin()}}; inherits from \code{margins}.}

\item{legend.box.background}{background of legend area (\code{\link[=element_rect]{element_rect()}};
inherits from \code{rect})}

\item{legend.box.spacing}{The spacing between the plotting area and the
legend box (\code{unit}); inherits from \code{spacing}.}

\item{panel.background}{background of plotting area, drawn underneath plot
(\code{\link[=element_rect]{element_rect()}}; inherits from \code{rect})}

\item{panel.border}{border around plotting area, drawn on top of plot so that
it covers tick marks and grid lines. This should be used with
\code{fill = NA}
(\code{\link[=element_rect]{element_rect()}}; inherits from \code{rect})}

\item{panel.spacing, panel.spacing.x, panel.spacing.y}{spacing between facet
panels (\code{unit}). \code{panel.spacing.x} & \code{panel.spacing.y} inherit from \code{panel.spacing}
or can be specified separately. \code{panel.spacing} inherits from \code{spacing}.}

\item{panel.grid, panel.grid.major, panel.grid.minor, panel.grid.major.x, panel.grid.major.y, panel.grid.minor.x, panel.grid.minor.y}{grid lines (\code{\link[=element_line]{element_line()}}). Specify major grid lines,
or minor grid lines separately (using \code{panel.grid.major} or \code{panel.grid.minor})
or individually for each axis (using \code{panel.grid.major.x}, \code{panel.grid.minor.x},
\code{panel.grid.major.y}, \code{panel.grid.minor.y}).  Y axis grid lines are horizontal
and x axis grid lines are vertical. \verb{panel.grid.*.*} inherits from
\verb{panel.grid.*} which inherits from \code{panel.grid}, which in turn inherits
from \code{line}}

\item{panel.ontop}{option to place the panel (background, gridlines) over
the data layers (\code{logical}). Usually used with a transparent or blank
\code{panel.background}.}

\item{panel.widths, panel.heights}{Sizes for panels (\code{units}). Can be a
single unit to set the total size for the panel area, or a unit vector to
set the size of individual panels. Using this setting overrides the
aspect ratio set by the theme, coord or facets. An exception is made when
the plot has a single panel and exactly one of the width \emph{or} height is
set, in which case an attempt is made to preserve the aspect ratio.}

\item{plot.background}{background of the entire plot (\code{\link[=element_rect]{element_rect()}};
inherits from \code{rect})}

\item{plot.title}{plot title (text appearance) (\code{\link[=element_text]{element_text()}}; inherits
from \code{title}) left-aligned by default}

\item{plot.title.position, plot.caption.position}{Alignment of the plot title/subtitle
and caption.  The setting for \code{plot.title.position} applies to both
the title and the subtitle. A value of "panel" (the default) means that
titles and/or caption are aligned to the plot panels. A value of "plot" means
that titles and/or caption are aligned to the entire plot (minus any space
for margins and plot tag).}

\item{plot.subtitle}{plot subtitle (text appearance) (\code{\link[=element_text]{element_text()}};
inherits from \code{title}) left-aligned by default}

\item{plot.caption}{caption below the plot (text appearance)
(\code{\link[=element_text]{element_text()}}; inherits from \code{title}) right-aligned by default}

\item{plot.tag}{upper-left label to identify a plot (text appearance)
(\code{\link[=element_text]{element_text()}}; inherits from \code{title}) left-aligned by default}

\item{plot.tag.position}{The position of the tag as a string ("topleft",
"top", "topright", "left", "right", "bottomleft", "bottom", "bottomright")
or a coordinate. If a coordinate, can be a numeric vector of length 2 to
set the x,y-coordinate relative to the whole plot. The coordinate option
is unavailable for \code{plot.tag.location = "margin"}.}

\item{plot.tag.location}{The placement of the tag as a string, one of
\code{"panel"}, \code{"plot"} or \code{"margin"}. Respectively, these will place the tag
inside the panel space, anywhere in the plot as a whole, or in the margin
around the panel space.}

\item{plot.margin}{margin around entire plot (\code{unit} with the sizes of
the top, right, bottom, and left margins); inherits from \code{margin}.}

\item{strip.background, strip.background.x, strip.background.y}{background of facet labels (\code{\link[=element_rect]{element_rect()}};
inherits from \code{rect}). Horizontal facet background (\code{strip.background.x})
& vertical facet background (\code{strip.background.y}) inherit from
\code{strip.background} or can be specified separately}

\item{strip.clip}{should strip background edges and strip labels be clipped
to the extend of the strip background? Options are \code{"on"} to clip, \code{"off"}
to disable clipping or \code{"inherit"} (default) to take the clipping setting
from the parent viewport.}

\item{strip.placement}{placement of strip with respect to axes,
either "inside" or "outside". Only important when axes and strips are
on the same side of the plot.}

\item{strip.text, strip.text.x, strip.text.y, strip.text.x.top, strip.text.x.bottom, strip.text.y.left, strip.text.y.right}{facet labels (\code{\link[=element_text]{element_text()}}; inherits from  \code{text}). Horizontal facet labels (\code{strip.text.x}) & vertical
facet labels (\code{strip.text.y}) inherit from \code{strip.text} or can be specified
separately. Facet strips have dedicated position-dependent theme elements
(\code{strip.text.x.top}, \code{strip.text.x.bottom}, \code{strip.text.y.left}, \code{strip.text.y.right})
that inherit from \code{strip.text.x} and \code{strip.text.y}, respectively.
As a consequence, some theme stylings need to be applied to
the position-dependent elements rather than to the parent elements}

\item{strip.switch.pad.grid, strip.switch.pad.wrap}{space between strips and
axes when strips are switched (\code{unit}); inherits from \code{spacing}.}

\item{complete}{set this to \code{TRUE} if this is a complete theme, such as
the one returned by \code{\link[=theme_grey]{theme_grey()}}. Complete themes behave
differently when added to a ggplot object. Also, when setting
\code{complete = TRUE} all elements will be set to inherit from blank
elements.}

\item{validate}{\code{TRUE} to run \code{check_element()}, \code{FALSE} to bypass checks.}
}
\description{
Themes are a powerful way to customize the non-data components of your plots:
i.e. titles, labels, fonts, background, gridlines, and legends. Themes can be
used to give plots a consistent customized look. Modify a single plot's theme
using \code{theme()}; see \code{\link[=theme_update]{theme_update()}} if you want modify the active theme, to
affect all subsequent plots. Use the themes available in \link[=theme_bw]{complete themes} if you would like to use a complete theme such as
\code{theme_bw()}, \code{theme_minimal()}, and more. Theme elements are documented
together according to inheritance, read more about theme inheritance below.
}
\section{Theme inheritance}{

Theme elements inherit properties from other theme elements hierarchically.
For example, \code{axis.title.x.bottom} inherits from \code{axis.title.x} which inherits
from \code{axis.title}, which in turn inherits from \code{text}. All text elements inherit
directly or indirectly from \code{text}; all lines inherit from
\code{line}, and all rectangular objects inherit from \code{rect}.
This means that you can modify the appearance of multiple elements by
setting a single high-level component.

Learn more about setting these aesthetics in \code{vignette("ggplot2-specs")}.
}

\examples{
p1 <- ggplot(mtcars, aes(wt, mpg)) +
  geom_point() +
  labs(title = "Fuel economy declines as weight increases")
p1

# Plot ---------------------------------------------------------------------
p1 + theme(plot.title = element_text(size = rel(2)))
p1 + theme(plot.background = element_rect(fill = "green"))

# Panels --------------------------------------------------------------------

p1 + theme(panel.background = element_rect(fill = "white", colour = "grey50"))
p1 + theme(panel.border = element_rect(linetype = "dashed"))
p1 + theme(panel.grid.major = element_line(colour = "black"))
p1 + theme(
  panel.grid.major.y = element_blank(),
  panel.grid.minor.y = element_blank()
)

# Put gridlines on top of data
p1 + theme(
  panel.background = element_rect(fill = NA),
  panel.grid.major = element_line(colour = "grey50"),
  panel.ontop = TRUE
)

# Axes ----------------------------------------------------------------------
# Change styles of axes texts and lines
p1 + theme(axis.line = element_line(linewidth = 3, colour = "grey80"))
p1 + theme(axis.text = element_text(colour = "blue"))
p1 + theme(axis.ticks = element_line(linewidth = 2))

# Change the appearance of the y-axis title
p1 + theme(axis.title.y = element_text(size = rel(1.5), angle = 90))

# Make ticks point outwards on y-axis and inwards on x-axis
p1 + theme(
  axis.ticks.length.y = unit(.25, "cm"),
  axis.ticks.length.x = unit(-.25, "cm"),
  axis.text.x = element_text(margin = margin(t = .3, unit = "cm"))
)

\donttest{
# Legend --------------------------------------------------------------------
p2 <- ggplot(mtcars, aes(wt, mpg)) +
  geom_point(aes(colour = factor(cyl), shape = factor(vs))) +
  labs(
    x = "Weight (1000 lbs)",
    y = "Fuel economy (mpg)",
    colour = "Cylinders",
    shape = "Transmission"
   )
p2

# Position
p2 + theme(legend.position = "none")
p2 + theme(legend.justification = "top")
p2 + theme(legend.position = "bottom")

# Or place legends inside the plot using relative coordinates between 0 and 1
# legend.justification sets the corner that the position refers to
p2 + theme(
  legend.position = "inside",
  legend.position.inside = c(.95, .95),
  legend.justification = c("right", "top"),
  legend.box.just = "right",
  legend.margin = margin_auto(6)
)

# The legend.box properties work similarly for the space around
# all the legends
p2 + theme(
  legend.box.background = element_rect(),
  legend.box.margin = margin_auto(6)
)

# You can also control the display of the keys
# and the justification related to the plot area can be set
p2 + theme(legend.key = element_rect(fill = "white", colour = "black"))
p2 + theme(legend.text = element_text(size = 8, colour = "red"))
p2 + theme(legend.title = element_text(face = "bold"))

# Strips --------------------------------------------------------------------

p3 <- ggplot(mtcars, aes(wt, mpg)) +
  geom_point() +
  facet_wrap(~ cyl)
p3

p3 + theme(strip.background = element_rect(colour = "black", fill = "white"))
p3 + theme(strip.text.x = element_text(colour = "white", face = "bold"))
# More direct strip.text.x here for top
# as in the facet_wrap the default strip.position is "top"
p3 + theme(strip.text.x.top = element_text(colour = "white", face = "bold"))
p3 + theme(panel.spacing = unit(1, "lines"))

# Colours -------------------------------------------------------------------

p4 <- ggplot(mtcars, aes(wt, mpg)) +
  geom_point() +
  annotate(label = "Text Annotation", x = 5, y = 30, geom = "text")

# You can use the 'ink' setting to set colour defaults for all layers
p4 + theme(geom = element_geom(ink = "dodgerblue"))
# Alternate colours are derived from the 'accent' and 'paper' settings
p4 + geom_smooth(method = "lm", formula = y ~ x) +
  theme(geom = element_geom(accent = "tomato", paper = "orchid"))
# You can also set default palettes in the theme
p4 + aes(colour = drat) +
  theme(palette.colour.continuous = c("white", "pink", "hotpink"))
}
}
\seealso{
\code{\link[=add_gg]{add_gg()}} and \code{\link[=get_theme]{\%+replace\%}},
\code{\link[=element_blank]{element_blank()}}, \code{\link[=element_line]{element_line()}},
\code{\link[=element_rect]{element_rect()}}, and \code{\link[=element_text]{element_text()}} for
details of the specific theme elements.

The \href{https://ggplot2-book.org/themes#modifying-theme-components}{modifying theme components} and \href{https://ggplot2-book.org/themes#sec-theme-elements}{theme elements sections} of the online ggplot2 book.
}