Skip to contents

Style a column as margin notes

Source: R/gt_marginalia.R
gt_marginalia.Rd

Styles a text column as commentary instead of data. It applies a muted color, italics, a hairline separating the notes from the figures, a blank column label, and a width constraint so the prose wraps instead of stretching the table.

Usage

gt_marginalia(
  gt_object,
  columns,
  width = 220,
  label = "",
  italic = TRUE,
  color = NULL,
  size = "0.92em",
  rule = TRUE,
  rule_color = NULL,
  align = "left"
)

Arguments

gt_object

A gt table object to modify.

columns

The column or columns to treat as margin notes.

width

Numeric. The column width in pixels, which is what makes the prose wrap. Pass NULL to leave the width alone. Defaults to 220.

label

Character. The column label. Defaults to "", since a note column rarely needs one; pass a string to keep a heading.

italic

Logical. Should the notes be italicized? Defaults to TRUE.

color

Optional. A hex color for the text. If NULL, a muted color is derived from the table background and checked for legibility. Defaults to NULL.

size

Character. The font size, as a CSS size. Defaults to "0.92em", slightly smaller than the body and scaling with whatever size the theme sets.

rule

Logical. Should a hairline be drawn on the left edge, separating the notes from the data? Defaults to TRUE.

rule_color

Optional. A hex color for that hairline. Derived from the table background when NULL. Defaults to NULL.

align

Character. The text alignment. Defaults to "left".

Value

Returns a modified gt table with the selected columns styled as margin notes.

Details

A text column with no width set runs to a single long line, so width is what wraps the prose. On a three-row example, that is the difference between a table 625 pixels wide and one 482 pixels wide.

Colors are derived from the table background instead of being hard-coded, so the treatment also reads correctly on a dark theme. That means the theme has to be applied first. An unthemed table reports a white background, and the notes come out too dark to read once a dark theme lands on top. Pass color and rule_color to fix them regardless of order.

See also

gt_cutline() for a labeled break between rows.

Examples

library(gt)

nfc_west <- subset(
  sdv_example_standings, division == "NFC West",
  c(team_name, wins, losses, conference_rank, playoff_wins)
)

# a note on each team's postseason, written from its own row
nfc_west$note <- with(nfc_west, ifelse(
  is.na(playoff_wins),
  "Missed the playoffs.",
  paste0(
    "The No. ", conference_rank, " seed; ", playoff_wins, " playoff win",
    ifelse(playoff_wins == 1, "", "s"), "."
  )
))

gt(nfc_west) |>
  gt_theme_broadsheet() |>
  gt_marginalia(note)



  
team_name
      wins
      losses
      conference_rank
      playoff_wins
      
    
Seattle Seahawks
14
3
1
3
The No. 1 seed; 3 playoff wins.
Los Angeles Rams
12
5
5
2
The No. 5 seed; 2 playoff wins.
San Francisco 49ers
12
5
6
1
The No. 6 seed; 1 playoff win.
Arizona Cardinals
3
14
16
NA
Missed the playoffs.

# keep a heading, widen it, and drop the italics
gt(nfc_west) |>
  gt_marginalia(note, label = "Postseason", width = 280, italic = FALSE)



  
team_name
      wins
      losses
      conference_rank
      playoff_wins
      Postseason
    
Seattle Seahawks
14
3
1
3
The No. 1 seed; 3 playoff wins.
Los Angeles Rams
12
5
5
2
The No. 5 seed; 2 playoff wins.
San Francisco 49ers
12
5
6
1
The No. 6 seed; 1 playoff win.
Arizona Cardinals
3
14
16
NA
Missed the playoffs.