cols_label: Relabel one or more columns

Description

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.

Usage

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

Value

An object of class gt_tbl.

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

Examples

Use countrypops to create a gt table. Relabel all the table's columns with the cols_label() function to improve its presentation.

countrypops %>%
  dplyr::select(-contains("code")) %>%
  dplyr::filter(country_name == "Mongolia") %>%
  tail(5) %>%
  gt() %>%
  cols_label(
    country_name = "Name",
    year = "Year",
    population = "Population"
  )

#' This image of a table was generated from the first code example in the `cols_label()` help file.

Using countrypops again to create a gt table, we label columns just as before but this time make the column labels bold through Markdown formatting.

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**")
  )

This image of a table was generated from the second code example in the `cols_label()` help file.

Function ID

4-4

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.