Add a spanner column label

Set a spanner column label by mapping it to columns already in the table. This label is placed above one or more column labels, spanning the width of those columns and column labels.

tab_spanner(data, label, columns, id = label, gather = TRUE)

Arguments

data	A table object that is created using the gt() function.
label	The text to use for the spanner column label.
columns	The columns to be components of the spanner heading.
id	The ID for the spanner column label. When accessing a spanner column label through cells_column_spanners() (when using tab_style() or tab_footnote()) the id value is used as the reference (and not the label). If an id is not explicitly provided here, it will be taken from the label value. It is advisable to set an explicit id value if you plan to access this cell in a later function call and the label text is complicated (e.g., contains markup, is lengthy, or both). Finally, when providing an id value you must ensure that it is unique across all ID values set for column spanner labels (the function will stop if id isn't unique).
gather	An option to move the specified columns such that they are unified under the spanner column label. Ordering of the moved-into-place columns will be preserved in all cases. By default, this is set to TRUE.

Value

An object of class gt_tbl.

Figures

Function ID

2-2

See also

Other Create or Modify Parts: tab_footnote(), tab_header(), tab_options(), tab_row_group(), tab_source_note(), tab_spanner_delim(), tab_stubhead(), tab_style()

Examples

# Use `gtcars` to create a gt table;
# Group several columns related to car
# performance under a spanner column
# with the label `performance`
tab_1 <-
  gtcars %>%
  dplyr::select(
    -mfr, -trim, bdy_style, drivetrain,
    -drivetrain, -trsmn, -ctry_origin
  ) %>%
  dplyr::slice(1:8) %>%
  gt(rowname_col = "model") %>%
  tab_spanner(
    label = "performance",
    columns = c(
      hp, hp_rpm, trq, trq_rpm,
      mpg_c, mpg_h)
  )