align: Align boxes

In Gmisc: Descriptive Statistics, Transition Plots, and More

Align boxes

Description

Aligns a set of boxGrob/boxPropGrob according to the first positional argument.

Align a list of boxes vertically or horizontally. Designed for piping ('|>').

Usage

alignVertical(
  reference,
  ...,
  position = c("center", "top", "bottom"),
  subelement = NULL
)

alignHorizontal(
  reference,
  ...,
  position = c("center", "left", "right"),
  sub_position = c("none", "left", "right"),
  subelement = NULL
)

align(x, ...)

## Default S3 method:
align(x, ...)

## S3 method for class 'list'
align(x, ...)

## S3 method for class 'Gmisc_list_of_boxes'
align(x, ..., axis = c("y", "x", "vertical", "horizontal"))

Arguments

reference	A boxGrob/boxPropGrob/coords object or a unit or a numerical value that can be converted into a unit of npc type. If a numeric scalar is provided and is 0 or greater than the number of boxes, it is treated as a coordinate (no error is raised).
...	Arguments passed to ['alignVertical'] or ['alignHorizontal'].
position	How to align the boxes, differs slightly for vertical and horizontal alignment see the accepted arguments
subelement	If a list of boxes is provided, this parameter can be used to target a specific element (by name or index), or a deep path into nested lists (e.g., c("detail", 1)), for the alignment operation. You can also provide multiple targets by giving a list of paths (e.g., list(c("detail", 1), c("followup", 1))). When a list of boxes is piped into alignVertical()/alignHorizontal() and a named reference is provided (e.g. my_boxes |> alignHorizontal(reference = c("grp","sub"), .subelement = ...)), the function will unwrap a single-element wrapper so nested .subelement targets are found as expected. The function will return the original list with the targeted element(s) replaced by their aligned version(s).
sub_position	When the box is a boxPropGrob it not only has the general .positions but also left and right which can be viewed as separate boxes that have simply been merged.
x	A 'list' of boxes.
axis	Orientation: '"y"'/'"vertical"' or '"x"'/'"horizontal"'.

Value

list with the boxes that are to be aligned

The aligned list of boxes (class 'Gmisc_list_of_boxes').

See Also

Other flowchart components: append(), boxGrob(), boxHeaderGrob(), boxPropGrob(), boxShapes, connectGrob(), coords(), distance(), flowchart(), insert(), move(), moveBox(), spread()

Other flowchart components: append(), boxGrob(), boxHeaderGrob(), boxPropGrob(), boxShapes, connectGrob(), coords(), distance(), flowchart(), insert(), move(), moveBox(), spread()

Examples

library(grid)
grid.newpage()

# Create a reference box
box <- boxGrob("A cool reference box",
  x = .5, y = .8,
  box_gp = gpar(fill = "#ADB5C7")
)

# Create a group of boxes to align
boxes <- list(
  another_box = boxGrob("A horizontal box", x = .1, y = .5),
  yet_another_box = boxGrob("Another horizontal box", x = .8, y = .3)
)

# Align the group and then individual boxes within that group
# (do not pipe the list into the function, as the first argument is `reference`)
aligned_boxes <- alignHorizontal(boxes, reference = box, position = "right") |>
  alignVertical(reference = .5, position = "center")

# Example: align a nested element inside a complex list using a deep path
complex_list <- list(
  arms = list(
    early = list(boxGrob("Early", x = .2, y = .4)),
    late = list(boxGrob("Late", x = .8, y = .2))
  ),
  detail = list(
    list(boxGrob("D_early", x = .1, y = .6)),
    list(boxGrob("D_late", x = .9, y = .1))
  )
)

# Align the first detail element to the early arm by deep path
complex_list <- complex_list |>
  alignHorizontal(
    reference = c("arms", "early"),
    position = "center",
    subelement = c("detail", 1)
  )

# Print the reference and the aligned boxes
box
aligned_boxes
complex_list

Gmisc documentation built on March 6, 2026, 9:09 a.m.