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)



A table object that is created using the gt() function.


The text to use for the spanner column label.


The columns to be components of the spanner heading.


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).


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.


An object of class gt_tbl.


Function ID


See also


# 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 %>%
    -mfr, -trim, bdy_style, drivetrain,
    -drivetrain, -trsmn, -ctry_origin
  ) %>%
  dplyr::slice(1:8) %>%
  gt(rowname_col = "model") %>%
    label = "performance",
    columns = c(
      hp, hp_rpm, trq, trq_rpm,
      mpg_c, mpg_h)