alignpatches: Arrange multiple plots into a grid

In ggalign: A 'ggplot2' Extension for Composable Visualization

Arrange multiple plots into a grid

Description

An internal S7 class that represents a collection of aligned plots along with their layout configuration, titles, tags, and theme.

Usage

alignpatches(
  ...,
  ncol = NULL,
  nrow = NULL,
  byrow = TRUE,
  widths = NA,
  heights = NA,
  area = NULL,
  guides = waiver(),
  theme = NULL,
  design = NULL
)

align_plots(
  ...,
  ncol = NULL,
  nrow = NULL,
  byrow = TRUE,
  widths = NA,
  heights = NA,
  area = NULL,
  guides = waiver(),
  theme = NULL,
  design = NULL
)

Arguments

...	<dyn-dots> A list of plots, ususally the ggplot object. Use NULL to indicate an empty spacer. Each input must implement the patch() method.
ncol, nrow	The number of columns and rows in the grid. Defaults to NULL. If both are NULL, the layout dimensions are determined automatically using the same logic as facet_wrap().
byrow	A logical value indicating whether plots should be filled in row-major order (TRUE) or column-major order (FALSE). Defaults to TRUE.
widths, heights	The relative widths and heights of each column and row in the grid. These values are recycled to match the grid dimensions. The special value NA is treated as a unit of ⁠1null⁠, unless a fixed-aspect plot is included — in that case, the affected dimension will expand or contract to maintain the aspect ratio of the plot. Defaults to NA.
area	A specification of the area layout. Can be defined either as a character string or as a combination of calls to area(). Defaults to NULL.
guides	A string with one or more of "t", "l", "b", "r", and "i" indicating which side of guide legends should be collected. Defaults to waiver(), which inherits from the parent layout. If there is no parent layout, or if NULL is provided, no guides will be collected.
theme	A theme() object used to customize various elements of the layout. By default, the theme will inherit from the parent layout.
design	An alias for area, retained for backward compatibility.

Value

An alignpatches object.

Properties

• plots: A list of plot objects.

• layout: A list specifying layout options, including:

  • ncol, nrow, byrow: grid layout parameters.

  • widths, heights: relative dimensions of rows/columns.

  • area: custom area specification.

  • guides: guide handling.

• titles: A list specifying title options (title, subtitle, caption).

• tags: A list specifying tag options (tags, sep, prefix, suffix).

• theme: A theme configuration object.

See Also

• layout_design()

• layout_title()

• layout_theme()

• layout_tags()

Examples

# directly copied from patchwork
p1 <- ggplot(mtcars) +
    geom_point(aes(mpg, disp))
p2 <- ggplot(mtcars) +
    geom_boxplot(aes(gear, disp, group = gear))
p3 <- ggplot(mtcars) +
    geom_bar(aes(gear)) +
    facet_wrap(~cyl)
p4 <- ggplot(mtcars) +
    geom_bar(aes(carb))
p5 <- ggplot(mtcars) +
    geom_violin(aes(cyl, mpg, group = cyl))

# Either add the plots as single arguments
align_plots(p1, p2, p3, p4, p5)

# Or use bang-bang-bang to add a list
align_plots(!!!list(p1, p2, p3), p4, p5)

# Match plots to areas by name
area <- "#BB
          AA#"
align_plots(B = p1, A = p2, area = area)

# Compare to not using named plot arguments
align_plots(p1, p2, area = area)

ggalign documentation built on Nov. 5, 2025, 7:16 p.m.