` for italic when rendering the text. Another example is [`ggh4x::element_part_rect()`](https://teunbrand.github.io/ggh4x/reference/element_part_rect.html) that can draw a subset of rectangle borders.
+
+
+
+### Hierarchy and inheritance
+
+Most theme elements are hierarchical. At the root, they are broadly applicable and change large parts of the plot. At leaves, they are very specific and allow fine grained control. Travelling from roots to leaves, properties of theme elements are inherited from parent to child. Some inheritance is very direct, where leaves directly inherit from roots (for example `legend.text`). Other times, inheritance is more arduous, like for `axis.minor.ticks.y.left`: it inherits from `axis.ticks.y.left`, which inherits from `axis.ticks.y`, which inherits from `axis.ticks`, which finally inherits from `line`. Most often, elements only have a single parent, but there are exceptions so the inheritance of theme elements is not strictly a directed acyclic graph.
+
+In the example below we set the root `text` element to red text. This is applied (almost) universally to all text in the plot. We also set the font of the leaf `legend.text` element. We see that not only has the legend text font changed, but it is red as well because of the root `text` element.
+
+
+
+
p + theme(
+ # A root element
+ text = element_text(colour = "red"),
+ # A leaf element
+ legend.text = element_text(family = "impact")
+)
+
+
+
+
+
+
# Will inherit entirely from parent
+theme_gray()$axis.ticks.x.bottom
+#> NULL
+
+# The element is incomplete
+theme_gray()$axis.ticks
+#> <ggplot2::element_line>
+#> @ colour : chr "#333333FF"
+#> @ linewidth : NULL
+#> @ linetype : NULL
+#> @ lineend : NULL
+#> @ linejoin : NULL
+#> @ arrow : logi FALSE
+#> @ arrow.fill : chr "#333333FF"
+#> @ inherit.blank: logi TRUE
+
+# Proper way to access the properties of an element
+calc_element("axis.ticks.x.bottom", theme_gray())
+#> <ggplot2::element_line>
+#> @ colour : chr "#333333FF"
+#> @ linewidth : num 0.5
+#> @ linetype : num 1
+#> @ lineend : chr "butt"
+#> @ linejoin : chr "round"
+#> @ arrow : logi FALSE
+#> @ arrow.fill : chr "#333333FF"
+#> @ inherit.blank: logi TRUE
+
+
+
+
+
tree <- get_element_tree()
+tree$axis.line.x.bottom$inherit
+#> [1] "axis.line.x"
+
+
+
+
+
+
+The [`theme()`](https://ggplot2.tidyverse.org/reference/theme.html) function has a lot of arguments and can be a bit overwhelming to parse in one take. At the time of writing, it has 147 arguments and `...` is obfuscating additional optional. Because we like structure rather than chaos, let us try to digest the [`theme()`](https://ggplot2.tidyverse.org/reference/theme.html) function one bite at a time. Much of the theme has been divided over parts in the `theme_sub_*()` family of functions. This family are just simple shortcuts. For example the `theme_sub_axis(title)` argument, populates the `axis.title` element.
+
+
+
+
theme_sub_axis(title = element_blank())
+#> <theme> List of 1
+#> $ axis.title: <ggplot2::element_blank>
+#> @ complete: logi FALSE
+#> @ validate: logi TRUE
+
+
+
+
+
p +
+ labs(tag = "A") +
+ theme_sub_plot(
+ # Adjust the background colour
+ background = element_rect(fill = "cornsilk"),
+
+ # Align title and subtitle to plot instead of panels
+ title = element_text(hjust = 0), # default,
+ subtitle = element_text(colour = "dodgerblue"),
+ title.position = "plot",
+
+ # Align caption to plot instead of panels
+ caption = element_text(hjust = 1), # default
+ caption.position = "plot",
+
+ # Place the tag in the top right of the panels instead of top left of plot
+ tag.position = "topright",
+ tag.location = "panel"
+ )
+
+
+
+
+
+
p +
+ theme_sub_panel(
+ # Extra space between panels
+ spacing.x = unit(1, "cm"),
+
+ # Tweaking all the grid elements
+ grid = element_line(colour = "grey80"),
+
+ # Turning off the minor grid elements
+ grid.minor = element_blank(),
+
+ # Tweak the major x/y lines separately
+ grid.major.x = element_line(linetype = "dotted"),
+ grid.major.y = element_line(colour = "white")
+ )
+
+
+
+
+
+
# We're including a labeller to showcase formatting
+my_labeller <- as_labeller(c(`1999` = "The Nineties", `2008` = "The Noughties",
+ V = "Vertical Strip"))
+p +
+ # Using a dummy strip for the vertical direction
+ facet_grid("V" ~ year, labeller = my_labeller, switch = "x") +
+ theme_sub_strip(
+ # All strip backgrounds
+ background = element_rect(fill = "cornsilk"),
+ # Specifically the horizontal strips
+ background.x = element_rect(colour = "black", linewidth = 1),
+ # Tweak text, specifically for the bottom strip
+ text.x.bottom = element_text(size = 16),
+
+ placement = "outside",
+ # Spacing in between axes and strips. Note that it doesn't affect the
+ # vertical strip that doesn't have an axis.
+ switch.pad.grid = unit(1, "cm"),
+ clip = "off"
+ )
+
+
+
+
+
+
p +
+ theme_sub_legend(
+ # Showing the box
+ box.background = element_rect(fill = "cornsilk"),
+
+ # Put legends on the left
+ position = "left",
+
+ # Arrange legends horizontally
+ box = "horizontal",
+
+ # Align to legend box to top
+ justification = "top",
+ # location = "plot",
+ # But align legends within the box at the bottom
+ box.just = "bottom",
+
+ # Spacings and margins
+ box.margin = margin_auto(5),
+ box.spacing = unit(1, "cm")
+ )
+
+
+
+
+
+
p +
+ guides(shape = guide_legend(position = "left")) +
+ theme_sub_legend(
+ # Showing the boxes
+ box.background = element_rect(fill = "cornsilk"),
+ box.margin = margin_auto(5),
+
+ # Tweaking the justification per position
+ justification.left = "top",
+ justification.right = "bottom"
+ )
+
+
+
+
+
+
p +
+ theme_sub_legend(
+ # Give guides a wider background
+ background = element_rect(fill = "cornsilk"),
+ margin = margin_auto(5, unit = "mm"),
+
+ # Display legend titles to the right of the guide
+ title = element_text(angle = 270),
+ title.position = "right",
+
+ # Display red labels to the left of the keys
+ text = element_text(colour = "red"),
+ text.position = "left",
+
+ # Set smaller keys
+ key.width = unit(5, "mm"),
+ key.height = unit(5, "mm")
+ )
+
+
+
+
+
+
p +
+ # Set two columns and long label text
+ scale_shape_discrete(
+ labels = c("4\nwheel\ndrive", "front\nwheel\ndrive", "rear\nwheel\ndrive"),
+ guide = guide_legend(ncol = 2)
+ ) +
+ theme_sub_legend(
+ # Fill items in grid in a row-wise fashion
+ byrow = TRUE,
+ # Increase spacing between keys
+ key.spacing.y = unit(5, "mm"),
+ key.spacing.x = unit(5, "mm"),
+ # Top-align keys with text
+ key.justification = "top"
+ )
+
+
+
+
+
+
p +
+ # Turn off grouping
+ aes(colour = NULL, shape = NULL) +
+ geom_smooth(formula = y ~ x, method = "lm") +
+ theme(
+ geom = element_geom(
+ ink = "tomato",
+ paper = "dodgerblue",
+ accent = "forestgreen"
+ )
+ )
+
+
+
+
+
+
element_geom()
+#> <ggplot2::element_geom>
+#> @ ink : NULL
+#> @ paper : NULL
+#> @ accent : NULL
+#> @ linewidth : NULL
+#> @ borderwidth: NULL
+#> @ linetype : NULL
+#> @ bordertype : NULL
+#> @ family : NULL
+#> @ fontsize : NULL
+#> @ pointsize : NULL
+#> @ pointshape : NULL
+#> @ colour : NULL
+#> @ fill : NULL
+
+
+
+
+
ggplot(faithful, aes(eruptions)) +
+ geom_histogram(aes(y = after_stat(density)), bins = 30, colour = "black") +
+ geom_line(stat = "density") +
+ theme(
+ geom = element_geom(
+ # Applies to the bars
+ borderwidth = 0.5,
+ bordertype = "dashed",
+ # Applies to the line
+ linewidth = 4,
+ linetype = "solid"
+ )
+ )
+
+
+
+
+
+
ggplot(mtcars, aes(mpg, disp, label = rownames(mtcars))) +
+ geom_point() +
+ geom_label(nudge_x = 0.25, hjust = 0) +
+ theme(
+ geom = element_geom(
+ # Point settings
+ pointsize = 8,
+ pointshape = "←",
+
+ # Text settings
+ fontsize = 8,
+ family = "Ink Free"
+ )
+ )
+
+
+
+
+
+
p + theme(
+ palette.shape.discrete = c("plus", "triangle", "diamond"),
+ palette.colour.continuous = c("maroon", "hotpink", "white")
+)
+
+
+
+
+
+
# A custom element comes up empty
+calc_element("my_element", complete_theme())
+#> NULL
+
+# Register element
+register_theme_elements(
+ my_element = element_rect(),
+ element_tree = list(
+ my_element = el_def(
+ class = "element_rect", # Must be a rect element
+ inherit = "rect" # Get settings from theme(rect)
+ )
+ )
+)
+
+# Now custom element can be computed
+calc_element("my_element", complete_theme())
+#> <ggplot2::element_rect>
+#> @ fill : chr "white"
+#> @ colour : chr "black"
+#> @ linewidth : num 0.5
+#> @ linetype : num 1
+#> @ linejoin : chr "round"
+#> @ inherit.blank: logi TRUE
+
+
+
+
+
my_theme <- function(...) {}
+
+
+
+
my_theme <- function(...) {
+ theme_gray(...)
+}
+
+
+
+
# Do *not* do the following!
+my_fragile_theme <- function(...) {
+ t <- theme_gray(...)
+ t$legend.text <- element_text() # BAD
+ t
+}
+
+
+
+
my_theme <- function(...) {
+ theme_gray(...) %+replace%
+ theme(
+ # Because we're replacing, we should fully define root elements
+ text = element_text(
+ family = "", face = "plain", colour = "red", size = 11,
+ hjust = 0.5, vjust = 0.5, angle = 0, lineheight = 1, margin = margin()
+ ),
+ # Non-root elements can be partially defined
+ legend.text = element_text(colour = "blue")
+ ) +
+ # Here we're updating the root line element with `+`, instead of replacing it
+ theme(line = element_line(linetype = "dotted"))
+}
+
+p + my_theme()
+
+
+
+
+
+
# Create a variable for your future theme
+cached_theme <- NULL
+
+# In your .onLoad function, construct the theme
+.onLoad <- function(libname, pkgname) {
+ cached_theme <<- my_theme()
+}
+
+# In your package's functions, you can now use the cached theme
+my_plotting_function <- function() {
+ ggplot(mpg, aes(displ, hwy)) +
+ geom_point() +
+ cached_theme
+}
+
+# Simulate loading
+.onLoad()
+
+# Works!
+my_plotting_function()
+
+
+
+
+
+
my_theme <- function(...) {
+ theme_gray() +
+ theme(
+ panel.background = element_blank(),
+ panel.grid = element_line(colour = "grey95"),
+ palette.colour.continuous = "viridis"
+ )
+}
+
+set_theme(my_theme())
+
+# Global goodness galore!
+p
+
+
+
+
+
+
my_theme <- function(header_family = "Impact", ...) {
+ systemfonts::require_font(header_family)
+ theme_gray(header_family = header_family, ...)
+}
+
+p + my_theme()
+
+
+
+
+
+
upper_legend <- function() {
+ theme(
+ plot.title.position = "plot",
+ legend.location = "plot",
+ legend.position = "top",
+ legend.justification.top = "left",
+ legend.title.position = "top",
+ legend.margin = margin_part(l = 0)
+ )
+}
+
+p +
+ aes(colour = NULL) +
+ upper_legend()
+
+
+
+
+
+
bottom_colourbar <- function() {
+ theme_sub_legend(
+ position = "bottom",
+ title.position = "top",
+ justification.bottom = "left",
+ # Stretch bar across width of panels
+ key.width = unit(1, "null"),
+ margin = margin_part(l = 0, r = 0)
+ )
+}
+
+p +
+ aes(shape = NULL) +
+ bottom_colourbar()
+
+
+
+
+
+
pattern <- "https://raw.githubusercontent.com/tidyverse/ggplot2/refs/heads/main/man/figures/logo.png" |>
+ magick::image_read() |>
+ grid::rasterGrob(
+ x = 0.8, y = 0.8,
+ width = unit(0.2, "snpc"),
+ height = unit(0.23, "snpc"),
+ ) |>
+ grid::pattern(extend = "none")
+
+p +
+ theme(
+ panel.background = element_rect(fill = pattern),
+ # legend.key inherits from panel background, so we tweak it
+ legend.key = element_blank(),
+ # make grid semitransparent to lay over pattern
+ panel.grid = element_line(colour = alpha("black", 0.05))
+ )
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+