Create 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).

gt()

Create a gt table object

gt_preview()

Preview a gt table object

Create or Modify Parts

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().

tab_header()

Add a table header

tab_spanner()

Add a spanner column label

tab_spanner_delim()

Create column labels and spanners via delimited names

tab_row_group()

Add a row group to a gt table

tab_stubhead()

Add label text to the stubhead

tab_footnote()

Add a table footnote

tab_source_note()

Add a source note citation

tab_style()

Add custom styles to one or more cells

tab_options()

Modify the table output options

Format 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 text_transform() function allows for post-processing of any data, and we provide a function for that transformation.

fmt_number()

Format numeric values

fmt_scientific()

Format values to scientific notation

fmt_percent()

Format values as a percentage

fmt_currency()

Format values as currencies

fmt_date()

Format values as dates

fmt_time()

Format values as times

fmt_datetime()

Format values as date-times

fmt_markdown()

Format Markdown text

fmt_passthrough()

Format by simply passing data through

fmt_missing()

Format missing values

fmt()

Set a column format with a formatter function

text_transform()

Perform targeted text transformation with a function

data_color()

Set data cell colors using a palette or a color function

Modify 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 (cols_merge*()), moving columns around (cols_move*())

cols_align()

Set the alignment of columns

cols_width()

Set the widths of columns

cols_label()

Relabel one or more columns

cols_move_to_start()

Move one or more columns to the start

cols_move_to_end()

Move one or more columns to the end

cols_move()

Move one or more columns

cols_hide()

Hide one or more columns

cols_merge_range()

Merge two columns to a value range column

cols_merge_uncert()

Merge two columns to a value & uncertainty column

cols_merge()

Merge data from two or more columns to a single column

Modify Rows

The only function currently that modifies entire rows is the row_group_order() function. It lets us modify the ordering of any row groups in the table.

row_group_order()

Modify the ordering of any row groups

Add 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.

summary_rows()

Add groupwise summary rows using aggregation functions

grand_summary_rows()

Add grand summary rows using aggregation functions

Helper Functions

A small 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 cells_styles() function is used exclusively with tab_style()’s style argument (and the px() & pct() functions may be 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.

md()

Interpret input text as Markdown-formatted text

html()

Interpret input text as HTML-formatted text

px()

Helper for providing a numeric value as pixels value

pct()

Helper for providing a numeric value as percentage

cells_title()

Location helper for targeting the table title and subtitle

cells_stubhead()

Location helper for targeting the table stubhead cell

cells_column_spanners()

Location helper for targeting the column spanners

cells_column_labels()

Location helper for targeting the column labels

cells_row_groups()

Location helper for targeting row groups

cells_stub()

Location helper for targeting cells in the table stub

cells_body()

Location helper for targeting data cells in the table body

cells_summary()

Location helper for targeting group summary cells

cells_grand_summary()

Location helper for targeting cells in a grand summary

currency()

Supply a custom currency symbol to fmt_currency()

cell_text()

Helper for defining custom text styles for table cells

cell_fill()

Helper for defining custom fills for table cells

cell_borders()

Helper for defining custom borders for table cells

adjust_luminance()

Adjust the luminance for a palette of colors

random_id()

Helper for creating a random id for a gt table

escape_latex()

Perform LaTeX escaping

gt_latex_dependencies()

Get the LaTeX dependencies required for a gt table

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.

web_image()

Helper function for adding an image from the web

local_image()

Helper function for adding a local image

ggplot_image()

Helper function for adding a ggplot

test_image()

Generate a path to a test image

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. For instance, we can modify the set of marks to use with footnotes, turn on row striping, change the alignment of the table header, and much more.

opt_footnote_marks()

Option to modify the set of footnote marks

opt_row_striping()

Option to add or remove row striping

opt_align_table_header()

Option to align the table header

opt_all_caps()

Option to use all caps in select table locations

opt_table_lines()

Option to set table lines to different extents

opt_table_outline()

Option to wrap an outline around the entire table

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()), and, on all of the different locales supported in the formatter functions (info_locales()).

info_date_style()

View a table with info on date styles

info_time_style()

View a table with info on time styles

info_currencies()

View a table with info on supported currencies

info_locales()

View a table with info on supported locales

info_paletteer()

View a table with info on color palettes

Datasets

The gt package is equipped with six datasets that come in all shapes and sizes. Use them to experiment with the package. Many examples in the internal help documents use these datasets to quickly demonstrate the key features of gt.

countrypops

Yearly populations of countries from 1960 to 2017

sza

Twice hourly solar zenith angles by month & latitude

gtcars

Deluxe automobiles from the 2014-2017 period

sp500

Daily S&P 500 Index data from 1950 to 2015

pizzaplace

A year of pizza sales from a pizza place

exibble

A toy example tibble for testing with gt: exibble

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).

render_gt()

A gt display table render function for use in Shiny

gt_output()

Create a gt display table output element for Shiny

Export 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().

gtsave()

Save a gt table as a file

as_raw_html()

Get the HTML content of a gt table

as_latex()

Output a gt object as LaTeX

as_rtf()

Output a gt object as RTF

extract_summary()

Extract a summary list from a gt object