Skip to contents

Create a gt table object

Source: R/gt.R
gt.Rd

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 = NULL,
  groupname_col = dplyr::group_vars(data),
  omit_na_group = FALSE,
  process_md = FALSE,
  caption = NULL,
  rownames_to_stub = FALSE,
  row_group_as_column = FALSE,
  auto_align = TRUE,
  id = NULL,
  locale = getOption("gt.locale"),
  row_group.sep = getOption("gt.row_group.sep", " - ")
)

Arguments

data

Input data table

obj:<data.frame>|obj:<tbl_df> // required

A data.frame object or a tibble (tbl_df).

rowname_col

Column(s) for row names/labels from data

vector<character> // default: NULL (optional)

The column name(s) in the input data table to use as row labels to be placed in the table stub. If multiple column names are provided, they will create a hierarchical stub layout where values from the leftmost column form the highest level of the hierarchy, proceeding to individual row identifiers in the rightmost column. If the rownames_to_stub option is TRUE then any column name provided to rowname_col will be ignored.

groupname_col

Column for group names/labels from data

scalar<character> // default: NULL (optional)

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

omit_na_group

Omit rows with NA in groupname_col from grouping

scalar<logical> // default: FALSE

Should rows with NA values in the groupname_col be excluded from row group assignment? By default (FALSE), rows with NA in groupname_col will be assigned to a group called "NA". When set to TRUE, rows with NA values will appear as ungrouped rows in the table body. This is useful when you want to include header or separator rows that shouldn't belong to any row group.

process_md

Process Markdown in rowname_col and groupname_col

scalar<logical> // default: FALSE

Should the contents of the rowname_col and groupname_col be interpreted as Markdown? By default this won't happen.

caption

Table caption text

scalar<character> // default: NULL (optional)

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

rownames_to_stub

Use data frame row labels in the stub

scalar<logical> // default: FALSE

An option to take rownames from the input data table (should they be available) as row labels in the display table stub.

row_group_as_column

Mode for displaying row group labels in the stub

scalar<logical> // default: FALSE

An option that alters the display of row group labels. By default this is FALSE and row group labels will appear in dedicated rows above their respective groups of rows. If TRUE row group labels will occupy a secondary column in the table stub.

auto_align

Automatic alignment of column values and labels

scalar<logical> // default: TRUE

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

scalar<character> // default: NULL (optional)

By default (with NULL) this will be a random, ten-letter ID as generated by using random_id(). A custom table ID can be used here by providing a character value.

locale

Locale identifier

scalar<character> // default: getOption("gt.locale") (optional)

An optional locale identifier that can be set as the default locale for all functions that take a locale argument. Examples include "en" for English (United States) and "fr" for French (France). We can call info_locales() as a useful reference for all of the locales that are supported. If set, options(gt.locale) is also consulted.

row_group.sep

Separator text for multiple row group labels

scalar<character> // default: getOption("gt.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 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 containing row labels through the use of the rowname_col argument. Further to this, stub row groups can be created with the groupname_col argument. Both arguments take the name of a column in the input table data. Typically, the data in the groupname_col column will consist of categorical text whereas the data in the rowname_col column will contain unique labels (could be unique across the entire table or unique within the different row groups).

Row groups can also be created by passing a grouped_df to gt() by using dplyr::group_by() 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 labels will appear in the display table.

Examples

Let's use the exibble dataset for the next few examples, we'll learn how to make simple gt tables with the gt() function. The most basic thing to do is to just use gt() with the dataset as the input.

exibble |> gt()

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

This dataset has the row and group columns. The former contains unique values that are ideal for labeling rows, and this often happens in what is called the 'stub' (a reserved area that serves to label rows). With the gt() function, we can immediately place the contents of the row column into the stub column. To do this, we use the rowname_col argument with the name of the column to use in quotes.

exibble |> gt(rowname_col = "row")

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

This sets up a table with a stub, the row labels are placed within the stub column, and a vertical dividing line has been placed on the right-hand side.

The group column can be used to divide the rows into discrete groups. Within that column, we see repetitions of the values grp_a and grp_b. These serve both as ID values and the initial label for the groups. With the groupname_col argument in gt(), we can set up the row groups immediately upon creation of the table.

exibble |>
  gt(
    rowname_col = "row",
    groupname_col = "group"
  )

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

If you'd rather perform the set up of row groups later (i.e., not in the gt() call), this is possible with tab_row_group() (and row_group_order() can help with the arrangement of row groups).

One more thing to consider with row groups is their layout. By default, row group labels reside in separate rows the appear above the group. However, we can use row_group_as_column = TRUE to put the row group labels within a secondary column within the table stub.

exibble |>
  gt(
    rowname_col = "row",
    groupname_col = "group",
    row_group_as_column = TRUE
  )

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

This could be done later if need be, and using tab_options(row_group.as_column = TRUE) would be the way to do it outside of the gt() call.

Some datasets have rownames built in; mtcars famously has the car model names as the rownames. To use those rownames as row labels in the stub, the rownames_to_stub = TRUE option will prove to be useful.

head(mtcars, 10) |> gt(rownames_to_stub = TRUE)

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

By default, values in the body of a gt table (and their column labels) are automatically aligned. The alignment is governed by the types of values in a column. If you'd like to disable this form of auto-alignment, the auto_align = FALSE option can be taken.

exibble |> gt(rowname_col = "row", auto_align = FALSE)

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

What you'll get from that is center-alignment of all table body values and all column labels. Note that row labels in the stub are still left-aligned; and auto_align has no effect on alignment within the table stub.

However which way you generate the initial gt table object, you can use it with a huge variety of functions in the package to further customize the presentation. Formatting body cells is commonly done with the family of formatting functions (e.g., fmt_number(), fmt_date(), etc.). The package supports formatting with internationalization ('i18n' features) and so locale-aware functions come with a locale argument. To avoid having to use that argument repeatedly, the gt() function has its own locale argument. Setting a locale in that will make it available globally. Here's an example of how that works in practice when setting locale = "fr" in gt() and using formatting functions:

exibble |>
  gt(
    rowname_col = "row",
    groupname_col = "group",
    locale = "fr"
  ) |>
  fmt_number() |>
  fmt_date(
    columns = date,
    date_style = "yMEd"
  ) |>
  fmt_datetime(
    columns = datetime,
    format = "EEEE, MMMM d, y",
    locale = "en"
  )

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

In this example, fmt_number() and fmt_date() understand that the locale for this table is "fr" (French), so the appropriate formatting for that locale is apparent in the num, currency, and date columns. However in fmt_datetime(), we explicitly use the "en" (English) locale. This overrides the "fr" default set for this table and the end result is dates formatted with the English locale in the datetime column.

Function ID

1-1

Function Introduced

v0.2.0.5 (March 31, 2020)

See also

Other table creation functions: gt_preview()