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.

## Usage

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

## Arguments

data

A data.frame object or a tibble.

rowname_col

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.

groupname_col

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.

caption

An optional table caption to use for cross-referencing in R Markdown documents and bookdown book projects.

rownames_to_stub

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

auto_align

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.

id

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.

locale

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.

row_group.sep

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.

## Value

An object of class gt_tbl.

## Details

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.

## Examples

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 %>%
gt(
rowname_col = "row",
groupname_col = "group"
)

tab_1

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"
) %>%
fmt_number(
columns = num,
decimals = 2
) %>%
cols_label(num = "number")

## Function ID

1-1

Other table creation functions: gt_preview()