Create Table

RStudio Cloud Example

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/Modify Parts

RStudio Cloud Example

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

Add a row group

tab_stubhead_label()

Add label text to the stubhead

tab_footnote()

Add a table footnote

tab_source_note()

Add a source note citation

tab_options()

Modify the table output options

tab_style()

Add custom styles to one or more cells

Format Data

RStudio Cloud Example

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

Set a column format with a formatter function

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

Format missing values

fmt_passthrough()

Format by simply passing data through

text_transform()

Perform targeted text transformation with a function

data_color()

Set data cell colors using a palette or a color function

Modify Columns

RStudio Cloud Example

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*()), and using a column name delimiter to create labels in the column spanner (cols_split_delim()).

cols_align()

Set the alignment of columns

cols_hide()

Hide one or more columns

cols_label()

Relabel one or more columns

cols_merge()

Merge two columns to a single column

cols_merge_range()

Merge two columns to a value range column

cols_merge_uncert()

Merge two columns to a value & uncertainty column

cols_move()

Move one or more columns

cols_move_to_end()

Move one or more columns to the end

cols_move_to_start()

Move one or more columns to the start

cols_split_delim()

Create group names and column labels via delimited names

Modify Rows

RStudio Cloud Example

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

RStudio Cloud Example

There is one function that will add rows to a gt table and that is the summary_rows() function. It’s useful for adding summary rows to any table that has row groups and a stub (which is required for summary row labels).

summary_rows()

Add summary rows using aggregation functions

Export Table

RStudio Cloud Example

There may come a day when you need to export a gt table to some specific format. We have functions for getting the HTML content of a gt table (as_raw_html()), getting LaTeX code (as_latex()), and getting rich text (as_rtf()). 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().

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

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

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.

cells_title() cells_column_labels() cells_group() cells_stub() cells_data() cells_summary()

Helpers for targeting multiple cells in different locations

cells_styles()

Helper for defining custom styles for table cells

reexports

Objects exported from other packages

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

escape_latex()

Perform LaTeX escaping

adjust_luminance()

Adjust the luminance for a palette of colors

Image Addition

RStudio Cloud Example

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

Information

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()), and, on currencies (info_currencies()).

info_date_style()

View a table with info on date styles

info_time_style()

View a table with info on time styles

info_paletteer()

View a table with info on many different color palettes

info_currencies()

View a table with info on supported currencies

Datasets

The gt package is equipped with six datasets. Use them to experiment with the API, they come in all shapes and sizes. Many examples in the internal help documents use these datasets to quickly demonstrate 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