Skip to contents

The gt() function creates a gt table object when provided with table data. Using this function is the first step in a typical gt workflow. Once we have the gt table object, we can perform styling transformations before rendering to a display table of various formats.


  rowname_col = "rowname",
  groupname_col = dplyr::group_vars(data),
  process_md = FALSE,
  caption = NULL,
  rownames_to_stub = FALSE,
  auto_align = TRUE,
  id = NULL,
  locale = NULL,
  row_group.sep = getOption("gt.row_group.sep", " - ")



A data.frame object or a tibble.


The column name in the input data table to use as row captions to be placed in the display table stub. If the rownames_to_stub option is TRUE then any column name provided to rowname_col will be ignored.


The column name in the input data table to use as group labels for generation of stub row groups. If the input data table has the grouped_df class (through use of the dplyr::group_by() function or associated group_by*() functions) then any input here is ignored.


Should the contents of the rowname_col and groupname_col be interpreted as Markdown? By default this is FALSE.


An optional table caption to use for cross-referencing in R Markdown, Quarto, or bookdown.


An option to take rownames from the input data table as row captions in the display table stub.


Optionally have column data be aligned depending on the content contained in each column of the input data. Internally, this calls cols_align(align = "auto") for all columns.


The table ID. By default, with NULL, this will be a random, ten-letter ID as generated by using the random_id() function. A custom table ID can be used with any single-length character vector.


An optional locale ID that can be set as the default locale for all functions that take a locale argument. Examples of valid locales include "en_US" for English (United States) and "fr_FR" for French (France). Refer to the information provided by the info_locales() to determine which locales are supported.


The separator to use between consecutive group names (a possibility when providing data as a grouped_df with multiple groups) in the displayed stub row group label.


An object of class gt_tbl.


There are a few data ingest options we can consider at this stage. We can choose to create a table stub with rowname captions using the rowname_col argument. Further to this, stub row groups can be created with the groupname_col. Both arguments take the name of a column in the input table data. Typically, the data in the groupname_col will consist of categories of data in a table and the data in the rowname_col are unique labels (perhaps unique across the entire table or unique within groups).

Row groups can also be created by passing a grouped_df to gt() by using the dplyr::group_by() function on the table data. In this way, two or more columns of categorical data can be used to make row groups. The row_group.sep argument allows for control in how the row group label will appear in the display table.


Create a gt table object using the exibble dataset. Use the row and group columns to add a stub and row groups via the rowname_col and groupname_col arguments.

tab_1 <-
  exibble %>%
    rowname_col = "row",
    groupname_col = "group"


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

The resulting gt table object can be used in transformations with a variety of tab_*(), fmt_*(), cols_*(), and even more functions available in the package.

tab_1 %>%
    title = "Table Title",
    subtitle = "Subtitle"
  ) %>%
    columns = num,
    decimals = 2
  ) %>%
  cols_label(num = "number")

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

Function ID


See also

Other table creation functions: gt_preview()