Create a gt table object — gt (2024)

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


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



Input data table

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

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


Column for row names/labels from data

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

The column name in the input data table to use as row labels to be placedin the table stub. If the rownames_to_stub option is TRUE then anycolumn name provided to rowname_col will be ignored.


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 forgeneration of row groups. If the input data table has the grouped_dfclass (through use of dplyr::group_by() or associated group_by*()functions) then any input here is ignored.


Process Markdown in rowname_col and groupname_col

scalar<logical> // default: FALSE

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


Table caption text

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

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


Use data frame row labels in the stub

scalar<logical> // default: FALSE

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


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 isFALSE and row group labels will appear in dedicated rows above theirrespective groups of rows. If TRUE row group labels will occupy asecondary column in the table stub.


Automatic alignment of column values and labels

scalar<logical> // default: TRUE

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


The table ID

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

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


Locale identifier

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

An optional locale identifier that can be set as the default locale for allfunctions that take a locale argument. Examples include "en" forEnglish (United States) and "fr" for French (France). We can callinfo_locales() as a useful reference for all of the locales that are supported.


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 whenproviding data as a grouped_df with multiple groups) in the displayedrow group label.


An object of class gt_tbl.


There are a few data ingest options we can consider at this stage. We canchoose to create a table stub containing row labels through the use of therowname_col argument. Further to this, stub row groups can be created withthe groupname_col argument. Both arguments take the name of a column in theinput table data. Typically, the data in the groupname_col column willconsist of categorical text whereas the data in the rowname_col column willcontain unique labels (could be unique across the entire table or uniquewithin the different row groups).

Row groups can also be created by passing a grouped_df to gt() by usingdplyr::group_by() on the table data. In this way, two or morecolumns of categorical data can be used to make row groups. Therow_group.sep argument allows for control in how the row group labels willappear in the display table.


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

exibble |> gt()

Create a gt table object — gt (1)

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

exibble |> gt(rowname_col = "row")

Create a gt table object — gt (2)

This sets up a table with a stub, the row labels are placed within the stubcolumn, 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 thegroupname_col argument in gt(), we can set up the row groups immediatelyupon creation of the table.

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

Create a gt table object — gt (3)

If you'd rather perform the set up of row groups later (i.e., not in thegt() 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, rowgroup 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 asecondary column within the table stub.

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

Create a gt table object — gt (4)

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

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

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

Create a gt table object — gt (5)

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 valuesin a column. If you'd like to disable this form of auto-alignment, theauto_align = FALSE option can be taken.

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

Create a gt table object — gt (6)

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

However which way you generate the initial gt table object, you can useit with a huge variety of functions in the package to further customize thepresentation. Formatting body cells is commonly done with the family offormatting functions (e.g., fmt_number(), fmt_date(), etc.). The packagesupports formatting with internationalization ('i18n' features) and solocale-aware functions come with a locale argument. To avoid having to usethat argument repeatedly, the gt() function has its own locale argument.Setting a locale in that will make it available globally. Here's an exampleof how that works in practice when setting locale = "fr" in gt() andusing 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" )

Create a gt table object — gt (7)

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

Function ID


Function Introduced

v0.2.0.5 (March 31, 2020)

See also

Other table creation functions: gt_preview()

Create a gt table object — gt (2024)
Top Articles
Latest Posts
Article information

Author: Rev. Leonie Wyman

Last Updated:

Views: 5263

Rating: 4.9 / 5 (59 voted)

Reviews: 82% of readers found this page helpful

Author information

Name: Rev. Leonie Wyman

Birthday: 1993-07-01

Address: Suite 763 6272 Lang Bypass, New Xochitlport, VT 72704-3308

Phone: +22014484519944

Job: Banking Officer

Hobby: Sailing, Gaming, Basketball, Calligraphy, Mycology, Astronomy, Juggling

Introduction: My name is Rev. Leonie Wyman, I am a colorful, tasty, splendid, fair, witty, gorgeous, splendid person who loves writing and wants to share my knowledge and understanding with you.