Create a gt table objectSource:
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.
Input data table
data.frameobject or a tibble (
Column for row names/labels from
The column name in the input
datatable to use as row labels to be placed in the table stub. If the
TRUEthen any column name provided to
rowname_colwill be ignored.
Column for group names/labels from
The column name in the input
datatable to use as group labels for generation of row groups. If the input
datatable has the
grouped_dfclass (through use of the
dplyr::group_by()function or associated
group_by*()functions) then any input here is ignored.
Process Markdown in
Should the contents of the
groupname_colbe interpreted as Markdown? By default this won't happen.
Table caption text
An optional table caption to use for cross-referencing in R Markdown, Quarto, or bookdown.
Use data frame row labels in the stub
An option to take rownames from the input
datatable (should they be available) as row labels in the display table stub.
Mode for displaying row group labels in the stub
An option that alters the display of row group labels. By default this is
FALSEand row group labels will appear in dedicated rows above their respective groups of rows. If
TRUErow group labels will occupy a secondary column in the table stub.
Automatic alignment of column values and labels
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 be providing a single-length character vector.
An optional locale identifier that can be set as the default locale for all functions that take a
localeargument. Examples include
"en"for English (United States) and
"fr"for French (France). We can use the
info_locales()function as a useful reference for all of the locales that are supported.
Separator text for multiple row group labels
getOption("gt.row_group.sep", " - ")
The separator to use between consecutive group names (a possibility when providing
grouped_dfwith multiple groups) in the displayed row group label.
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
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
gt() by using
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 labels will
appear in the display table.
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 dataset has the
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
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 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.
group column can be used to divide the rows into discrete groups.
Within that column, we see repetitions of the values
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" )
If you'd rather perform the set up of row groups later (i.e., not in the
gt() call), this is possible with use of the
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 the
row_group_as_column = TRUE option 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 could be done later if need be, and using
tab_options(row_group.as_column = TRUE) would be the way to do it outside
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.
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)
What you'll get from that is center-alignment of all table body values and
all column labels. Note that row labels in the the stub are still
auto_align has no effect on alignment within the table
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_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
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
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" )
In this example, the
fmt_date() functions understand
that the locale for this table is
"fr" (French), so the appropriate
formatting for that locale is apparent in the
columns. However in the
fmt_datetime() call, we explicitly use the
(English) locale. This overrides the
"fr" default set for this table and
the end result is dates formatted with the English locale in the
Other table creation functions: