ggtext

https://github.com/wilkelab/ggtext
Admin
ggtext is an R package that provides improved Markdown and HTML text rendering support for ggplot2,...
Tokens:15,305
Snippets:129
Trust Score:8.6
License:GPL-2.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install ggtext

Source: https://github.com/wilkelab/ggtext/blob/master/docs/index.html

Commands to install the stable version from CRAN or the development version from GitHub.

```R
install.packages("ggtext")
```

```R
remotes::install_github("wilkelab/ggtext")
```

--------------------------------

### Reproducible Example Placeholder

Source: https://github.com/wilkelab/ggtext/blob/master/ISSUE_TEMPLATE.md

Use this block to insert a reprex generated by the reprex package when reporting issues.

```r
# insert reprex here
```

--------------------------------

### Initialize a basic ggplot2 plot

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/introduction.html

Sets up a standard ggplot2 plot object to be used in subsequent examples.

```R
library(ggplot2)
library(ggtext)

base <- ggplot(data.frame(x = c(-5, 5)), aes(x)) +
  stat_function(fun = ~ .x*.x)

base
```

--------------------------------

### element_textbox_simple(family = NULL, face = NULL, size = NULL, colour = NULL, fill = NA, box.colour = NULL, linetype = 0, linewidth = 0.5, hjust = 0.5, vjust = 0.5, halign = 0, valign = 1, lineheight = 1.2, margin = NULL, padding = NULL, width = NULL, height = NULL, minwidth = NULL, maxwidth = NULL, minheight = NULL, maxheight = NULL, r = NULL, orientation = "upright", color = NULL, box.color = NULL, debug = FALSE, inherit.blank = FALSE)

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/element_textbox.html

Creates a theme element for markdown text in a box, providing meaningful default values for easier integration into existing themes.

```APIDOC
## element_textbox_simple

### Description
Creates a ggplot2 theme element that enables markdown text in a box. This function provides pre-defined default values for most parameters, making it simpler to use within existing themes.

### Parameters
- **family** (string) - Optional - Font family
- **face** (string) - Optional - Font face
- **size** (numeric) - Optional - Font size in pt
- **colour/color** (string) - Optional - Text color
- **fill** (string) - Optional - Fill color of the box (default: NA)
- **linetype** (numeric) - Optional - Line type (default: 0)
- **linewidth** (numeric) - Optional - Line width (default: 0.5)
- **hjust/vjust** (numeric) - Optional - Justification (default: 0.5)
- **halign/valign** (numeric) - Optional - Alignment (default: 0, 1)
- **lineheight** (numeric) - Optional - Line height (default: 1.2)
- **orientation** (string) - Optional - Text box orientation (default: "upright")

### Returns
A ggplot2 theme element.
```

--------------------------------

### Define element_textbox_simple parameters

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/element_textbox.html

Constructor function for creating a textbox theme element with pre-defined default values.

```R
element_textbox_simple(
  family = NULL,
  face = NULL,
  size = NULL,
  colour = NULL,
  fill = NA,
  box.colour = NULL,
  linetype = 0,
  linewidth = 0.5,
  hjust = 0.5,
  vjust = 0.5,
  halign = 0,
  valign = 1,
  lineheight = 1.2,
  margin = ggplot2::margin(0, 0, 0, 0),
  padding = ggplot2::margin(0, 0, 0, 0),
  width = grid::unit(1, "npc"),
  height = NULL,
  minwidth = NULL,
  maxwidth = NULL,
  minheight = NULL,
  maxheight = NULL,
  r = grid::unit(0, "pt"),
  orientation = "upright",
  color = NULL,
  box.color = NULL,
  debug = FALSE,
  inherit.blank = FALSE
)
```

--------------------------------

### element_textbox(family = NULL, face = NULL, size = NULL, colour = NULL, fill = NULL, box.colour = NULL, linetype = NULL, linewidth = NULL, hjust = NULL, vjust = NULL, halign = NULL, valign = NULL, lineheight = NULL, margin = NULL, padding = NULL, width = NULL, height = NULL, minwidth = NULL, maxwidth = NULL, minheight = NULL, maxheight = NULL, r = NULL, orientation = NULL, color = NULL, box.color = NULL, debug = FALSE, inherit.blank = FALSE)

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/element_textbox.html

Creates a theme element for markdown text in a box, where unspecified values are inherited from parent theme elements.

```APIDOC
## element_textbox

### Description
Creates a ggplot2 theme element that enables markdown text in a box. Unspecified parameters default to NULL and are completed by inheritance from parent theme elements.

### Parameters
- **family** (string) - Optional - Font family
- **face** (string) - Optional - Font face
- **size** (numeric) - Optional - Font size in pt
- **colour/color** (string) - Optional - Text color
- **fill** (string) - Optional - Fill color of the box
- **box.colour/box.color** (string) - Optional - Line color of the box
- **linetype** (numeric/string) - Optional - Line type of the box
- **linewidth** (numeric) - Optional - Line width of the box in mm
- **hjust/vjust/halign/valign** (numeric) - Optional - Justification settings
- **margin/padding** (unit) - Optional - Spacing around the box
- **width/height** (unit) - Optional - Dimensions of the box
- **r** (unit) - Optional - Corner radius of the box

### Returns
A ggplot2 theme element.
```

--------------------------------

### Inherit theme settings for Markdown labels

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/introduction.html

Shows how theme inheritance works by setting shared parameters in the parent axis.title element.

```R
base +
  labs(
    x = "independent variable *x*",
    y = "dependent variable *y* = *x*<sup>2</sup>"
  ) +
  theme(
    axis.title = element_text(color = "blue", size = rel(0.8)),
    axis.title.x = element_markdown(),
    axis.title.y = element_markdown()
  )
```

--------------------------------

### Prepare markdown labels

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/plotting_text.html

Update label strings to include markdown syntax for italics and superscripts.

```R
library(ggtext)

iris_cor_md <- iris_cor %>% 
  mutate(
    # markdown version of text label
    label = glue("*r*<sup>2</sup> = {round(r_square, 2)}")
  )

iris_cor_md
```

--------------------------------

### Load ggplot2 library

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/element_textbox.html

Initializes the ggplot2 library for use with ggtext elements.

```R
library(ggplot2)
```

--------------------------------

### element_textbox() / element_textbox_simple()

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/index.html

Theme elements that enable markdown text within a box.

```APIDOC
## element_textbox() / element_textbox_simple()

### Description
Theme element that enables markdown text in a box.
```

--------------------------------

### Rotate text boxes

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/plotting_text.html

Demonstrates placing text boxes in four distinct 90-degree orientations using the orientation aesthetic.

```R
df <- data.frame(
  x = 0.5,
  y = 0.5,
  label = "The quick brown fox jumps over the lazy dog.",
  orientation = c("upright", "left-rotated", "inverted", "right-rotated")
)

ggplot() +
  geom_textbox(
    data = df,
    aes(x, y, label = label, orientation = orientation),
    width = grid::unit(1.5, "in"),
    height = grid::unit(1.5, "in"),
    box.margin = grid::unit(rep(0.25, 4), "in"),
    hjust = 0, vjust = 1
  ) +
  xlim(0, 1) + ylim(0, 1) +
  scale_discrete_identity(aesthetics = "orientation")
```

--------------------------------

### Render Markdown in Theme Elements

Source: https://github.com/wilkelab/ggtext/blob/master/docs/index.html

Demonstrates using element_markdown() to apply custom styling and HTML tags to axis labels and plot captions.

```R
library(tidyverse)
library(ggtext)
library(glue)

data <- tibble(
  bactname = c("Staphylococcaceae", "Moraxella", "Streptococcus", "Acinetobacter"),
  OTUname = c("OTU 1", "OTU 2", "OTU 3", "OTU 4"),
  value = c(-0.5, 0.5, 2, 3)
)

data %>% mutate(
  color = c("#009E73", "#D55E00", "#0072B2", "#000000"),
  name = glue("<i style='color:{color}'>{bactname}</i> ({OTUname})"),
  name = fct_reorder(name, value)
)  %>%
  ggplot(aes(value, name, fill = color)) + 
  geom_col(alpha = 0.5) + 
  scale_fill_identity() +
  labs(caption = "Example posted on **stackoverflow.com**<br>(using made-up data)") +
  theme(
    axis.text.y = element_markdown(),
    plot.caption = element_markdown(lineheight = 1.2)
  )
```

--------------------------------

### Create a base plot with markdown title

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/theme_elements.html

Sets up a base ggplot2 object with a multi-line markdown title for subsequent styling.

```R
base <- mtcars %>%
  mutate(
    transmission = ifelse(am == 1, "automatic", "manual")
  ) %>%
  ggplot(aes(hp, mpg, color = transmission)) +
  geom_point(size = 2) +
  scale_color_manual(
    values = c(automatic = "#0072B2", manual = "#D55E00"),
    guide = "none"
  ) +
  labs(
    x = "Horse power",
    y = "Miles per gallon (MPG)",
    title = "Transmission type impacts fuel efficiency<br>
<span style = 'font-size:10pt;'>Miles per gallon (MPG) is on average higher for cars
with <span style = 'color:#0072B2;'>automatic transmission</span> than for cars with
<span style = 'color:#D55E00;'>manual transmission.</span> However, MPG generally
declines with increasing horse power.</span>"
  ) +
  theme_bw() + theme(plot.title.position = "plot")
```

--------------------------------

### Define element_textbox parameters

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/element_textbox.html

Constructor function for creating a textbox theme element with standard ggplot2 inheritance behavior.

```R
element_textbox(
  family = NULL,
  face = NULL,
  size = NULL,
  colour = NULL,
  fill = NULL,
  box.colour = NULL,
  linetype = NULL,
  linewidth = NULL,
  hjust = NULL,
  vjust = NULL,
  halign = NULL,
  valign = NULL,
  lineheight = NULL,
  margin = NULL,
  padding = NULL,
  width = NULL,
  height = NULL,
  minwidth = NULL,
  maxwidth = NULL,
  minheight = NULL,
  maxheight = NULL,
  r = NULL,
  orientation = NULL,
  color = NULL,
  box.color = NULL,
  debug = FALSE,
  inherit.blank = FALSE
)
```

--------------------------------

### Configure axis titles with markdown

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/introduction.html

Demonstrates the difference between incorrect and correct theme element targeting when using markdown in right-aligned axis titles.

```R
base +
  labs(
    x = "independent variable *x*",
    y = "dependent variable *y* = *x*<sup>2</sup>"
  ) +
  scale_y_continuous(position = "right") +
  theme(
    axis.title = element_text(color = "blue", size = rel(0.8)),
    axis.title.x = element_markdown(),
    axis.title.y = element_markdown()
  )
```

```R
base +
  labs(
    x = "independent variable *x*",
    y = "dependent variable *y* = *x*<sup>2</sup>"
  ) +
  scale_y_continuous(position = "right") +
  theme(
    axis.title = element_text(color = "blue", size = rel(0.8)),
    axis.title.x = element_markdown(),
    axis.title.y.right = element_markdown()
  )
```

--------------------------------

### Create text boxes with element_textbox_simple

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/introduction.html

Uses element_textbox_simple to wrap long title text into a formatted box.

```R
base <- mtcars %>%
  mutate(
    transmission = ifelse(am == 1, "automatic", "manual")
  ) %>%
  ggplot(aes(hp, mpg, color = transmission)) +
  geom_point(size = 2) +
  scale_color_manual(
    values = c(automatic = "#0072B2", manual = "#D55E00"),
    guide = "none"
  ) +
  labs(
    x = "Horse power",
    y = "Miles per gallon (MPG)",
    title = "Transmission type impacts fuel efficiency<br>
<span style = 'font-size:10pt;'>Miles per gallon (MPG) is on average higher for cars
with <span style = 'color:#0072B2;'>automatic transmission</span> than for cars with
<span style = 'color:#D55E00;'> manual transmission.</span> However, MPG generally
declines with increasing horse power.</span>"
  ) +
  theme_bw() + theme(plot.title.position = "plot")

base +
  theme(
    plot.title = element_textbox_simple(
      size = 14, lineheight = 1, padding = margin(0, 0, 5, 0)
    )
  )
```

--------------------------------

### element_markdown(family = NULL, face = NULL, size = NULL, colour = NULL, fill = NULL, box.colour = NULL, linetype = NULL, linewidth = NULL, hjust = NULL, vjust = NULL, halign = NULL, valign = NULL, angle = NULL, lineheight = NULL, margin = NULL, padding = NULL, r = NULL, color = NULL, box.color = NULL, align_widths = NULL, align_heights = NULL, rotate_margins = NULL, debug = FALSE, inherit.blank = FALSE)

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/element_markdown.html

Creates a theme element for rendering markdown text in ggplot2. This function is intended to be used within a ggplot2::theme() call.

```APIDOC
## element_markdown

### Description
Creates a ggplot2 theme element that enables markdown text rendering. This element can be used to style text labels within a plot theme.

### Parameters
- **family** (string) - Optional - Font family
- **face** (string) - Optional - Font face
- **size** (numeric) - Optional - Font size
- **colour, color** (string) - Optional - Text color
- **fill** (string) - Optional - Fill color of the enclosing box
- **box.colour, box.color** (string) - Optional - Line color of the enclosing box
- **linetype** (string/numeric) - Optional - Line type of the enclosing box
- **linewidth** (numeric) - Optional - Line width of the enclosing box in mm
- **hjust** (numeric) - Optional - Horizontal justification
- **vjust** (numeric) - Optional - Vertical justification
- **halign** (numeric) - Optional - Horizontal justification
- **valign** (numeric) - Optional - Vertical justification
- **angle** (numeric) - Optional - Angle in degrees
- **lineheight** (numeric) - Optional - Line height
- **margin** (margin) - Optional - Margins around the text box
- **padding** (margin) - Optional - Padding around the text box
- **r** (unit) - Optional - Corner radius of the box
- **align_widths** (boolean) - Optional - Align multiple elements by width
- **align_heights** (boolean) - Optional - Align multiple elements by height
- **rotate_margins** (boolean) - Optional - Whether margins rotate with text
- **debug** (boolean) - Optional - Draw a debugging box around each label
- **inherit.blank** (boolean) - Optional - Whether to inherit blank settings

### Value
A ggplot2 theme element.
```

--------------------------------

### element_markdown()

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/index.html

A theme element that enables markdown text rendering.

```APIDOC
## element_markdown()

### Description
Theme element that enables markdown text.
```

--------------------------------

### geom_richtext(mapping = NULL, data = NULL, stat = "identity", position = "identity", ..., nudge_x = 0, nudge_y = 0, label.padding = unit(c(0.25, 0.25, 0.25, 0.25), "lines"), label.margin = unit(c(0, 0, 0, 0), "lines"), label.r = unit(0.15, "lines"), na.rm = FALSE, show.legend = NA, inherit.aes = TRUE)

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/geom_richtext.html

Draws text labels formatted using basic markdown/html. Styling parameters like label.colour, label.padding, label.margin, label.size, and label.r control the appearance of the frame around the label.

```APIDOC
## geom_richtext

### Description
Draws text labels formatted using basic markdown/html. This geom is similar to ggplot2::geom_label() but supports rich text formatting.

### Parameters
- **mapping** (aes) - Optional - Set of aesthetic mappings created by aes() or aes_().
- **data** (data.frame) - Optional - The data to be displayed in this layer.
- **stat** (string) - Optional - The statistical transformation to use on the data for this layer.
- **position** (string/function) - Optional - Position adjustment.
- **nudge_x** (numeric) - Optional - Horizontal adjustment to nudge labels.
- **nudge_y** (numeric) - Optional - Vertical adjustment to nudge labels.
- **label.padding** (unit) - Optional - Amount of padding around label. Defaults to 0.25 lines.
- **label.margin** (unit) - Optional - Unit vector of length four specifying the margin outside the text label.
- **label.r** (unit) - Optional - Radius of rounded corners. Defaults to 0.15 lines.
- **na.rm** (logical) - Optional - If FALSE, missing values are removed with a warning. If TRUE, silently removed.
- **show.legend** (logical) - Optional - Should this layer be included in the legends?
- **inherit.aes** (logical) - Optional - If FALSE, overrides the default aesthetics.
```

--------------------------------

### Configure axis titles with element_markdown

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/theme_elements.html

Demonstrates the failure of naive axis title configuration when using a right-positioned y-axis.

```R
base +
  labs(
    x = "independent variable *x*",
    y = "dependent variable *y* = *x*<sup>2</sup>"
  ) +
  scale_y_continuous(position = "right") +
  theme(
    axis.title = element_text(color = "blue", size = rel(0.8)),
    axis.title.x = element_markdown(),
    axis.title.y = element_markdown()
  )
```

--------------------------------

### Replace facet strips with text boxes

Source: https://github.com/wilkelab/ggtext/blob/master/docs/index.html

Uses element_textbox within theme() to customize facet strip appearance.

```R
library(cowplot)

ggplot(mpg, aes(cty, hwy)) + 
  geom_point() +
  facet_wrap(~class) +
  theme_half_open(12) +
  background_grid() +
  theme(
    strip.background = element_blank(),
    strip.text = element_textbox(
      size = 12,
      color = "white", fill = "#5D729D", box.color = "#4A618C",
      halign = 0.5, linetype = 1, r = unit(5, "pt"), width = unit(1, "npc"),
      padding = margin(2, 0, 1, 0), margin = margin(3, 3, 3, 3)
    )
  )
```

--------------------------------

### Mapping label colors and fills

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/plotting_text.html

Assign label fill and text colors using aesthetic mappings or direct specification.

```R
iris_facets + 
  aes(colour = Species) +
  geom_richtext(
    data = iris_cor_md,
    aes(
      label = label,
      fill = after_scale(alpha(colour, .2))
    ),
    text.colour = "black",
    hjust = 1, vjust = 1
  ) +
  theme(legend.position = "none")
```

--------------------------------

### Style Markdown axis labels

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/introduction.html

Demonstrates modifying appearance properties like color and size within element_markdown().

```R
base +
  labs(
    x = "independent variable *x*",
    y = "dependent variable *y* = *x*<sup>2</sup>"
  ) +
  theme(
    axis.title.x = element_markdown(color = "blue"),
    axis.title.y = element_markdown(size = rel(0.8))
  )
```

--------------------------------

### Apply basic textbox styling

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/theme_elements.html

Applies element_textbox_simple to the plot title with basic size and padding adjustments.

```R
base +
  theme(
    plot.title = element_textbox_simple(
      size = 14, lineheight = 1, padding = margin(0, 0, 5, 0)
    )
  )
```

--------------------------------

### Render formatted text boxes with ggplot2

Source: https://github.com/wilkelab/ggtext/blob/master/docs/index.html

Creates a tibble with text labels and styling parameters, then renders them using geom_textbox in a ggplot2 plot.

```R
df <- tibble(
  label = rep("Lorem ipsum dolor **sit amet,** consectetur adipiscing elit,
    sed do *eiusmod tempor incididunt* ut labore et dolore magna
    aliqua.", 2),
  x = c(0, .6),
  y = c(1, .6),
  hjust = c(0, 0),
  vjust = c(1, 0),
  orientation = c("upright", "right-rotated"),
  color = c("black", "blue"),
  fill = c("cornsilk", "white")
)

ggplot(df) +
  aes(
    x, y, label = label, color = color, fill = fill,
    hjust = hjust, vjust = vjust,
    orientation = orientation
  ) +
  geom_textbox(width = unit(0.4, "npc")) +
  geom_point(color = "black", size = 2) +
  scale_discrete_identity(aesthetics = c("color", "fill", "orientation")) +
  xlim(0, 1) + ylim(0, 1)
```

--------------------------------

### Plot standard text labels

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/plotting_text.html

Render the prepared labels using the standard geom_text function.

```R
iris_facets <- ggplot(iris, aes(Sepal.Length, Sepal.Width)) +
  geom_point() + 
  geom_smooth(method = "lm", formula = y ~ x) +
  facet_wrap(~Species) +
  theme_bw()

iris_facets + 
  geom_text(
    data = iris_cor,
    aes(label = label),
    hjust = 1, vjust = 1
  )
```

--------------------------------

### Create a textbox plot with geom_textbox

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/geom_textbox.html

Demonstrates how to use geom_textbox to render markdown-formatted text boxes with custom orientation and styling.

```R
library(ggplot2)

df <- data.frame(
  label = rep("Lorem ipsum dolor **sit amet,** consectetur adipiscing elit,
    sed do *eiusmod tempor incididunt* ut labore et dolore magna
    aliqua.", 2),
  x = c(0, .6),
  y = c(1, .6),
  hjust = c(0, 0),
  vjust = c(1, 0),
  orientation = c("upright", "right-rotated"),
  color = c("black", "blue"),
  fill = c("cornsilk", "white")
)

ggplot(df) +
  aes(
    x, y, label = label, color = color, fill = fill,
    hjust = hjust, vjust = vjust,
    orientation = orientation
  ) +
  geom_textbox(width = unit(0.4, "npc")) +
  geom_point(color = "black", size = 2) +
  scale_discrete_identity(aesthetics = c("color", "fill", "orientation")) +
  xlim(0, 1) + ylim(0, 1)
```

--------------------------------

### Styling facet labels with element_textbox

Source: https://github.com/wilkelab/ggtext/blob/master/README.md

Use element_textbox within theme() to style facet strip labels with markdown/HTML support.

```r
library(cowplot)

ggplot(mpg, aes(cty, hwy)) + 
  geom_point() +
  facet_wrap(~class) +
  theme_half_open(12) +
  background_grid() +
  theme(
    strip.background = element_blank(),
    strip.text = element_textbox(
      size = 12,
      color = "white", fill = "#5D729D", box.color = "#4A618C",
      halign = 0.5, linetype = 1, r = unit(5, "pt"), width = unit(1, "npc"),
      padding = margin(2, 0, 1, 0), margin = margin(3, 3, 3, 3)
    )
  )
#> Warning: The `size` argument of `element_line()` is deprecated as of ggplot2 3.4.0.
#> Please use the `linewidth` argument instead.
#> Warning: The `size` argument of `element_rect()` is deprecated as of ggplot2 3.4.0.
#> Please use the `linewidth` argument instead.
```

--------------------------------

### Prepare data for standard text labels

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/plotting_text.html

Calculate correlation values and format labels for use with standard ggplot2 geoms.

```R
library(ggplot2)
library(dplyr)
library(glue)

iris_cor <- iris %>% 
  group_by(Species) %>%
  summarize(r_square = cor(Sepal.Length, Sepal.Width)^2) %>%
  mutate(
    # location of each text label in data coordinates
    Sepal.Length = 8, Sepal.Width = 4.5,
    # text label containing r^2 value 
    label = glue("r^2 = {round(r_square, 2)}")
  )

iris_cor
```

--------------------------------

### Apply inline CSS and multi-line labels

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/introduction.html

Uses element_markdown to style plot titles with HTML/CSS and includes line breaks.

```R
library(dplyr)

mtcars %>%
  mutate(
    transmission = ifelse(am == 1, "automatic", "manual")
  ) %>%
  ggplot(aes(hp, mpg, color = transmission)) +
  geom_point(size = 2) +
  scale_color_manual(
    values = c(automatic = "#0072B2", manual = "#D55E00"),
    guide = "none"
  ) +
  labs(
    x = "Horse power",
    y = "Miles per gallon (MPG)",
    title = "<span style = 'font-size:14pt; font-family:Helvetica;'>Transmission type impacts fuel efficiency</span><br>
MPG is higher for <span style = 'color:#0072B2;'>automatic</span>
than for <span style = 'color:#D55E00;'>manual</span> transmissions"
  ) +
  theme_bw() +
  theme(
    text = element_text(family = "Times"),
    plot.title.position = "plot",
    plot.title = element_markdown(size = 11, lineheight = 1.2)
  )
```

--------------------------------

### Render markdown labels with geom_richtext

Source: https://github.com/wilkelab/ggtext/blob/master/docs/index.html

Demonstrates using geom_richtext to place markdown-formatted labels with rotation and custom styling.

```R
df <- tibble(
  label = c(
    "Some text **in bold.**",
    "Linebreaks<br>Linebreaks<br>Linebreaks",
    "*x*<sup>2</sup> + 5*x* + *C*<sub>*i*</sub>",
    "Some <span style='color:blue'>blue text **in bold.**</span><br>And *italics text.*<br>
    And some <span style='font-size:18pt; color:black'>large</span> text."
  ),
  x = c(.2, .1, .5, .9),
  y = c(.8, .4, .1, .5),
  hjust = c(0.5, 0, 0, 1),
  vjust = c(0.5, 1, 0, 0.5),
  angle = c(0, 0, 45, -45),
  color = c("black", "blue", "black", "red"),
  fill = c("cornsilk", "white", "lightblue1", "white")
)


ggplot(df) +
  aes(
    x, y, label = label, angle = angle, color = color, fill = fill,
    hjust = hjust, vjust = vjust
  ) +
  geom_richtext() +
  geom_point(color = "black", size = 2) +
  scale_color_identity() +
  scale_fill_identity() +
  xlim(0, 1) + ylim(0, 1)
```

--------------------------------

### Initialize geom_richtext

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/geom_richtext.html

The function signature for geom_richtext, defining parameters for data mapping, statistical transformations, and label styling.

```R
geom_richtext(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  nudge_x = 0,
  nudge_y = 0,
  label.padding = unit(c(0.25, 0.25, 0.25, 0.25), "lines"),
  label.margin = unit(c(0, 0, 0, 0), "lines"),
  label.r = unit(0.15, "lines"),
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)
```

--------------------------------

### Render rich text labels with geom_richtext

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/geom_richtext.html

Demonstrates how to use geom_richtext to display formatted text with custom colors, angles, and backgrounds.

```R
library(ggplot2)

df <- data.frame(
  label = c(
    "Some text **in bold.**",
    "Linebreaks<br>Linebreaks<br>Linebreaks",
    "*x*<sup>2</sup> + 5*x* + *C*<sub>*i*</sub>",
    "Some <span style='color:blue'>blue text **in bold.**</span><br>And *italics text.*<br>
      And some <span style='font-size:18pt; color:black'>large</span> text."
  ),
  x = c(.2, .1, .5, .9),
  y = c(.8, .4, .1, .5),
  hjust = c(0.5, 0, 0, 1),
  vjust = c(0.5, 1, 0, 0.5),
  angle = c(0, 0, 45, -45),
  color = c("black", "blue", "black", "red"),
  fill = c("cornsilk", "white", "lightblue1", "white")
)

ggplot(df) +
  aes(
    x, y, label = label, angle = angle, color = color, fill = fill,
    hjust = hjust, vjust = vjust
  ) +
  geom_richtext() +
  geom_point(color = "black", size = 2) +
  scale_color_identity() +
  scale_fill_identity() +
  xlim(0, 1) + ylim(0, 1)
```

--------------------------------

### Apply Markdown to axis labels

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/introduction.html

Uses element_markdown() to render Markdown syntax within axis titles.

```R
base +
  labs(
    x = "independent variable *x*",
    y = "dependent variable *y* = *x*<sup>2</sup>"
  ) +
  theme(
    axis.title.x = element_markdown(),
    axis.title.y = element_markdown()
  )
```

--------------------------------

### geom_textbox()

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/index.html

A geom for drawing boxes containing text.

```APIDOC
## geom_textbox()

### Description
Draw boxes containing text.
```

--------------------------------

### Render rich text labels without background or frame

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/geom_richtext.html

Shows how to remove the background and outline from geom_richtext labels by setting fill and label.color to NA.

```R
# labels without frame or background are also possible
ggplot(df) +
  aes(
    x, y, label = label, angle = angle, color = color,
    hjust = hjust, vjust = vjust
  ) +
  geom_richtext(
    fill = NA, label.color = NA, # remove background and outline
    label.padding = grid::unit(rep(0, 4), "pt") # remove padding
  ) +
  geom_point(color = "black", size = 2) +
  scale_color_identity() +
  xlim(0, 1) + ylim(0, 1)
```

--------------------------------

### Create a basic text box in ggplot2

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/plotting_text.html

Defines a data frame with label text and uses geom_textbox to render it within a plot.

```R
df <- data.frame(
  x = 0.1,
  y = 0.8,
  label = "*Lorem ipsum dolor sit amet,* consectetur adipiscing
elit. Quisque tincidunt eget arcu in pulvinar. Morbi varius leo
vel consectetur luctus. **Morbi facilisis justo non fringilla.**
Vivamus sagittis sem felis, vel lobortis risus mattis eget. Nam
quis imperdiet felis, in convallis elit."
)

p <- ggplot() +
  geom_textbox(
    data = df,
    aes(x, y, label = label),
    width = grid::unit(0.73, "npc"), # 73% of plot panel width
    hjust = 0, vjust = 1
  ) +
  xlim(0, 1) + ylim(0, 1)

p
```

--------------------------------

### Render rich text in ggplot2 elements

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/element_textbox.html

Use element_textbox_simple to style and format text labels with HTML and CSS-like properties within a ggplot2 theme.

```R
ggplot(mtcars, aes(disp, mpg)) + 
geom_point() +
  labs(
    title =
    "<b><span style = 'font-size:13pt'>Fuel economy vs. engine displacement</span></b><br>
    Lorem ipsum *dolor sit amet,* consectetur adipiscing elit, **sed do eiusmod tempor
    incididunt** ut labore et dolore magna aliqua. <span style = 'color:red;'>Ut enim ad
    minim veniam,</span> quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
    commodo consequat.",
    x = "displacement (in<sup>3</sup>)",
    y = "Miles per gallon (mpg)<br><span style = 'font-size:8pt'>A measure of
    the car's fuel efficiency.</span>"
  ) +
  theme(
    plot.title.position = "plot",
    plot.title = element_textbox_simple(
      size = 10,
      padding = margin(5.5, 5.5, 5.5, 5.5),
      margin = margin(0, 0, 5.5, 0),
      fill = "cornsilk"
    ),
    axis.title.x = element_textbox_simple(
      width = NULL,
      padding = margin(4, 4, 4, 4),
      margin = margin(4, 0, 0, 0),
      linetype = 1,
      r = grid::unit(8, "pt"),
      fill = "azure1"
    ),
    axis.title.y = element_textbox_simple(
      hjust = 0,
      orientation = "left-rotated",
      minwidth = unit(1, "in"),
      maxwidth = unit(2, "in"),
      padding = margin(4, 4, 2, 4),
      margin = margin(0, 0, 2, 0),
      fill = "lightsteelblue1"
    )
  )
```

--------------------------------

### Rotate text boxes with orientation

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/introduction.html

Uses the orientation parameter to rotate a text box, demonstrated here on an axis title.

```R
mtcars %>%
  mutate(
    transmission = ifelse(am == 1, "automatic", "manual")
  ) %>%
  ggplot(aes(hp, mpg, color = transmission)) +
  geom_point(size = 2) +
  scale_color_manual(
    values = c(automatic = "#0072B2", manual = "#D55E00"),
    guide = "none"
  ) +
  labs(
    x = "Horse power",
    y = "Miles per gallon (MPG) is on average higher for cars with <span style =
    'color:#0072B2;'>automatic transmission</span> than for cars with <span style =
    'color:#D55E00;'>manual transmission.</span>",
    title = "Transmission type impacts fuel efficiency"
  ) +
  theme_bw() + 
  theme(
    plot.title.position = "plot",
    axis.title.y = element_textbox_simple(
      orientation = "left-rotated",
      width = grid::unit(2.5, "in"),
      hjust = 0, fill = "#F0F7FF",  
      padding = margin(5, 5, 5, 5),
      margin = margin(0, 0, 10, 0)
    )
  )
```

--------------------------------

### element_textbox_simple()

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/element_textbox.html

A theme element function used to style text labels in ggplot2 with markdown support and box properties.

```APIDOC
## element_textbox_simple()

### Description
Creates a theme element for rendering text with markdown support, allowing for custom padding, margins, background fill, and border styling within ggplot2 plots.

### Parameters
- **size** (numeric) - Optional - Font size of the text.
- **padding** (margin) - Optional - Padding around the text box.
- **margin** (margin) - Optional - Margin around the text box.
- **fill** (string) - Optional - Background color of the text box.
- **width** (unit) - Optional - Fixed width of the text box.
- **minwidth** (unit) - Optional - Minimum width of the text box.
- **maxwidth** (unit) - Optional - Maximum width of the text box.
- **linetype** (numeric) - Optional - Type of line for the border.
- **r** (unit) - Optional - Corner radius for the text box.
- **hjust** (numeric) - Optional - Horizontal justification of the text.
- **orientation** (string) - Optional - Orientation of the text (e.g., 'left-rotated').
```

--------------------------------

### Plot markdown labels

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/plotting_text.html

Render the markdown-formatted labels using geom_richtext.

```R
iris_facets + 
  geom_richtext(
    data = iris_cor_md,
    aes(label = label),
    hjust = 1, vjust = 1
  )
```

--------------------------------

### Render rich text in plot titles and axis labels

Source: https://github.com/wilkelab/ggtext/blob/master/docs/index.html

Uses element_textbox_simple to style plot titles and axis labels with markdown and HTML formatting.

```R
ggplot(mtcars, aes(disp, mpg)) + 
  geom_point() +
  labs(
    title = "<b>Fuel economy vs. engine displacement</b><br>
    <span style = 'font-size:10pt'>Lorem ipsum *dolor sit amet,*
    consectetur adipiscing elit, **sed do eiusmod tempor incididunt** ut
    labore et dolore magna aliqua. <span style = 'color:red;'>Ut enim
    ad minim veniam,</span> quis nostrud exercitation ullamco laboris nisi
    ut aliquip ex ea commodo consequat.</span>",
    x = "displacement (in<sup>3</sup>)",
    y = "Miles per gallon (mpg)<br><span style = 'font-size:8pt'>A measure of
    the car's fuel efficiency.</span>"
  ) +
  theme(
    plot.title.position = "plot",
    plot.title = element_textbox_simple(
      size = 13,
      lineheight = 1,
      padding = margin(5.5, 5.5, 5.5, 5.5),
      margin = margin(0, 0, 5.5, 0),
      fill = "cornsilk"
    ),
    axis.title.x = element_textbox_simple(
      width = NULL,
      padding = margin(4, 4, 4, 4),
      margin = margin(4, 0, 0, 0),
      linetype = 1,
      r = grid::unit(8, "pt"),
      fill = "azure1"
    ),
    axis.title.y = element_textbox_simple(
      hjust = 0,
      orientation = "left-rotated",
      minwidth = unit(1, "in"),
      maxwidth = unit(2, "in"),
      padding = margin(4, 4, 2, 4),
      margin = margin(0, 0, 2, 0),
      fill = "lightsteelblue1"
    )
  )
```

--------------------------------

### geom_textbox(mapping = NULL, data = NULL, stat = "identity", position = "identity", ..., nudge_x = 0, nudge_y = 0, box.padding = unit(c(5.5, 5.5, 5.5, 5.5), "pt"), box.margin = unit(c(0, 0, 0, 0), "pt"), box.r = unit(5.5, "pt"), width = unit(2, "inch"), minwidth = NULL, maxwidth = NULL, height = NULL, minheight = NULL, maxheight = NULL, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE)

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/geom_textbox.html

Draws boxes of defined width and height containing word-wrapped text in a ggplot2 plot.

```APIDOC
## geom_textbox

### Description
Draws boxes of defined width and height containing word-wrapped text. Multiple boxes can be drawn at once, and most styling parameters can be used as aesthetics.

### Arguments
- **mapping** (aes) - Optional - Set of aesthetic mappings.
- **data** (data.frame) - Optional - The data to be displayed in this layer.
- **stat** (string) - Optional - The statistical transformation to use.
- **position** (string/function) - Optional - Position adjustment.
- **nudge_x, nudge_y** (numeric) - Optional - Horizontal and vertical adjustment to nudge text boxes.
- **box.padding** (unit) - Optional - Unit vector of length four specifying the padding inside the text box.
- **box.margin** (unit) - Optional - Unit vector of length four specifying the margin outside the text box.
- **box.r** (unit) - Optional - Unit vector of length one specifying the radius of the box.
- **width, height** (unit) - Optional - Unit values specifying the width and height of the text box.
- **minwidth, maxwidth, minheight, maxheight** (unit) - Optional - Minimum and maximum constraints for width and height.
- **na.rm** (logical) - Optional - Whether to remove missing values.
- **show.legend** (logical) - Optional - Whether to include this layer in the legends.
- **inherit.aes** (logical) - Optional - Whether to inherit default aesthetics.

### Value
A ggplot2 layer that can be added to a plot created with ggplot2::ggplot().
```

--------------------------------

### Render labels without background or frame

Source: https://github.com/wilkelab/ggtext/blob/master/docs/index.html

Configures geom_richtext to remove background and outline by setting fill and label.color to NA.

```R
ggplot(df) +
  aes(
    x, y, label = label, angle = angle, color = color,
    hjust = hjust, vjust = vjust
  ) +
  geom_richtext(
    fill = NA, label.color = NA, # remove background and outline
    label.padding = grid::unit(rep(0, 4), "pt") # remove padding
  ) +
  geom_point(color = "black", size = 2) +
  scale_color_identity() +
  xlim(0, 1) + ylim(0, 1)
```

--------------------------------

### Style a text box with background and border in ggplot2

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/introduction.html

Configures a plot title using element_textbox_simple to add a background color, border, and internal padding.

```R
base +
  theme(
    plot.title = element_textbox_simple(
      size = 14, lineheight = 1,
      linetype = 1, # turn on border
      box.color = "#748696", # border color
      fill = "#F0F7FF", # background fill color
      r = grid::unit(3, "pt"), # radius for rounded corners
      padding = margin(5, 5, 5, 5), # padding around text inside the box
      margin = margin(0, 0, 10, 0) # margin outside the box
    )
  )
```

--------------------------------

### geom_richtext()

Source: https://github.com/wilkelab/ggtext/blob/master/docs/reference/index.html

A geom for rendering richtext labels.

```APIDOC
## geom_richtext()

### Description
Richtext labels.
```

--------------------------------

### Correct axis title configuration for right-positioned y-axis

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/theme_elements.html

Shows the correct approach by targeting the specific axis element (axis.title.y.right) for markdown rendering.

```R
base +
  labs(
    x = "independent variable *x*",
    y = "dependent variable *y* = *x*<sup>2</sup>"
  ) +
  scale_y_continuous(position = "right") +
  theme(
    axis.title = element_text(color = "blue", size = rel(0.8)),
    axis.title.x = element_markdown(),
    axis.title.y.right = element_markdown()
  )
```

--------------------------------

### Rotating text labels

Source: https://github.com/wilkelab/ggtext/blob/master/docs/articles/plotting_text.html

Apply rotation to text labels using the angle parameter.

```R
iris_facets + 
  aes(colour = Species) +
  geom_richtext(
    data = iris_cor_md,
    aes(
      x = 7.5,
      label = label,
      fill = after_scale(alpha(colour, .2))
    ),
    text.colour = "black",
    hjust = 1, vjust = 1,
    angle = 30
  ) +
  theme(legend.position = "none")
```
Tokens:
Raw