Relabel one or more columns

Column labels can be modified from their default values (the names of the columns from the input table data). When you create a gt table object using gt(), column names effectively become the column labels. While this serves as a good first approximation, column names aren't often appealing as column labels in a gt output table. The cols_label() function provides the flexibility to relabel one or more columns and we even have the option to use the md() or html() helper functions for rendering column labels from Markdown or using HTML.

cols_label(data, ..., .list = list2(...))

Arguments

data	A table object that is created using the gt() function.
...	One or more named arguments of column names from the input data table along with their labels for display as the column labels. We can optionally wrap the column labels with md() (to interpret text as Markdown) or html() (to interpret text as HTML).
.list	Allows for the use of a list as an input alternative to ....

Value

An object of class gt_tbl.

Details

It's important to note that while columns can be freely relabeled, we continue to refer to columns by their original column names. Column names in a tibble or data frame must be unique whereas column labels in gt have no requirement for uniqueness (which is useful for labeling columns as, say, measurement units that may be repeated several times---usually under different spanner column labels). Thus, we can still easily distinguish between columns in other gt function calls (e.g., in all of the fmt*() functions) even though we may lose distinguishability in column labels once they have been relabeled.

Figures

Function ID

4-3

See also

Other Modify Columns: cols_align(), cols_hide(), cols_merge_range(), cols_merge_uncert(), cols_merge(), cols_move_to_end(), cols_move_to_start(), cols_move(), cols_width()

Examples

# Use `countrypops` to create a gt table;
# label all the table's columns to
# present better
tab_1 <-
  countrypops %>%
  dplyr::select(-contains("code")) %>%
  dplyr::filter(country_name == "Mongolia") %>%
  tail(5) %>%
  gt() %>%
  cols_label(
    country_name = "Name",
    year = "Year",
    population = "Population"
  )

# Use `countrypops` to create a gt table;
# label columns as before but make them
# bold with markdown formatting
tab_2 <-
  countrypops %>%
  dplyr::select(-contains("code")) %>%
  dplyr::filter(country_name == "Mongolia") %>%
  tail(5) %>%
  gt() %>%
  cols_label(
    country_name = md("**Name**"),
    year = md("**Year**"),
    population = md("**Population**")
  )