With the gt package, we can build display tables from tabular data with an easy-to-use set of functions. With its progressive approach, we can construct display tables with a cohesive set of table parts. Table values can be formatted using any of the included formatting functions. Footnotes and cell styles can be precisely added through a location targeting system. The way in which gt handles things for you means that you don’t often have to worry about the fine details.

Creating a table

All gt tables begin with a call to gt(), where we would supply the input data table (data frame or tibble) and some basic options for creating a stub (rowname_col) and row groups (groupname_col). We can also introduce a grouped tibble (via dplyr’s group_by()) for more precise divisions of rows into row groups. The gt_preview() function is great for getting a nicely-formatted preview of a data table (defaulting to the first 5 rows and the last row).

Creating or modifying parts of a table

A gt table can contain a few useful parts for conveying additional information. These include a header (with a titles and subtitle), a footer (with footnotes and source notes), and additional areas for labels (row group labels, column spanner labels, the stubhead label). We can modify the look of table parts more generally with tab_options() and perform styling on targeted table locations with tab_style().

Formatting data

Columns of data can be formatted with the fmt_*() functions. We can specify the rows of these columns quite precisely with the rows argument. We get to apply these functions exactly once to each data cell (last call wins). Need to do custom formatting? Use the fmt() function and define your own formatter within (or, create a wrapper with fmt() if you prefer). The sub_*() functions allow you to perform substitution operations and data_color() provides a lot of power for colorizing body cells based on their data values.

Text transformation functions

The text_*() functions take cell data that are solidified into strings and allow for flexible transformations of those string values. Whereas the fmt_*() and sub_*() are phases 1 and 2 of cell data metamorphoses, the text transformation functions are the final phase, acting on strings generated by formatting and substitution functions with no reference to the source values.

Modifying columns

The cols_*() functions allow for modifications that act on entire columns. This includes alignment of the data in columns (cols_align()), hiding columns from view (cols_hide()), re-labeling the column labels (cols_label()), merging two columns together (the cols_merge*() functions), and moving columns around (the cols_move*() functions).

Adding or modifying rows

There are two functions that will add rows to a gt table: summary_rows() and grand_summary_rows(). These functions will both add summary rows but one will do it in a groupwise fashion while the other will create grand summary rows. The row_group_order() function lets us modify the ordering of any row groups in the table.

Removing parts of a table

The rm_*() functions let us safely remove parts of a gt table. This can be advantageous in those instances where you would obtain a gt table but prefer to excise some parts of it.

Helper functions

An assortment of helper functions is available in the gt package. The various cells_*() functions are used for targeting cells with the locations argument in the tab_footnote(), tab_style(), and text_transform() functions. The cell_*() functions are used exclusively with tab_style()’s style argument. The px() & pct() functions are useful there for specifying units in pixels or percentages. The md() and html() helpers can used be during label creation with the tab_header(), tab_footnote(), tab_spanner(), tab_stubhead_label(), and tab_source_note() functions.

Image addition functions

We can add images into a gt table with the help of the *_image() functions. Two common ways to do this: (1) use text_transform() to insert images into data cells, (2) use any function that creates new labels (e.g., tab_header()) and use a *_image() function within the html() helper.

Table option functions

With the opt_*() functions, we have an easy way to set commonly-used table options without having to use tab_options() directly. Like, we can quickly add a stylizing theme with opt_stylize(), get an interactive HTML table with opt_interactive(), modify the appearance of footnote marks with opt_footnote_marks() and opt_footnote_spec(), turn on row striping, change the alignment of the table header, and so much more.

Information functions

These info_*() functions present us with gt tables containing useful information. So far, we can get reference information on date styles (info_date_style()), on time styles (info_time_style()), on a huge number of color palettes (info_paletteer()), on currencies (info_currencies()), on all of the different locales supported in the formatter functions (info_locales()), and on our recommendations for which Google Fonts to try in your tables (info_google_fonts()).

Shiny functions

Shiny is great for building interactive web apps with R. There’s really nothing quite like it. The gt package includes two functions that work nicely with Shiny: a table render function render_gt() (for the server) and a table output element gt_output() (for the ui).

Export and extraction functions

There may come a day when you need to export a gt table to some specific format. A great function for that is gtsave(), which allows us to save as an HTML file or an image file. Some other functions give us table code as a character vector (e.g., as_raw_html()). Did you use the summary_rows() function and wish you had that summary data in a tibble? You can get it out with extract_summary(). Want to extract already-formatted cells from the table into a vector? Do it with extract_cells()!

Vector formatting functions

Why should columns have all the formatting fun? If you have vectors in need of formatting, we have a set of vec_fmt_*() functions that have been adapted from the corresponding fmt_*() functions.