gtsave: Save a *gt* table as a file

In rstudio/gt: Easily Create Presentation-Ready Display Tables

Save a gt table as a file

Description

gtsave() makes it easy to save a gt table to a file. The function guesses the file type by the extension provided in the output filename, producing either an HTML, PDF, PNG, LaTeX, RTF, or Word (.docx) file.

Usage

gtsave(data, filename, path = NULL, ...)

Arguments

data	The gt table data object ⁠obj:<gt_tbl>⁠ // required This is the gt table object that is commonly created through use of the gt() function.
filename	Output filename ⁠scalar<character>⁠ // required The file name to create on disk. Ensure that an extension compatible with the output types is provided (.html, .tex, .ltx, .rtf, .docx). If a custom save function is provided then the file extension is disregarded.
path	Output path ⁠scalar<character>⁠ // default: NULL (optional) An optional path to which the file should be saved (combined with filename).
...	Additional options ⁠<named arguments>⁠ All other options passed to the appropriate internal saving function.

Details

Output filenames with either the .html or .htm extensions will produce an HTML document. In this case, we can pass a TRUE or FALSE value to the inline_css option to obtain an HTML document with inlined CSS styles (the default is FALSE). More details on CSS inlining are available at as_raw_html(). We can pass values to arguments in htmltools::save_html() through the .... Those arguments are either background or libdir, please refer to the htmltools documentation for more details on the use of these arguments.

If the output filename is expressed with the .rtf extension then an RTF file will be generated. In this case, there is an option that can be passed through ...: page_numbering. This controls RTF document page numbering and, by default, page numbering is not enabled (i.e., page_numbering = "none").

We can create an image file based on the HTML version of the gt table. With the filename extension .png, we get a PNG image file. A PDF document can be generated by using the .pdf extension. This process is facilitated by the webshot2 package, so, this package needs to be installed before attempting to save any table as an image file. There is the option of passing values to the underlying webshot2::webshot() function through .... Some of the more useful arguments for PNG saving are zoom (defaults to a scale level of 2) and expand (adds whitespace pixels around the cropped table image, and has a default value of 5), and selector (the default value is "table"). There are several more options available so have a look at the webshot2 documentation for further details.

If the output filename extension is either of .tex, .ltx, or .rnw, a LaTeX document is produced. An output filename of .rtf will generate an RTF document. The LaTeX and RTF saving functions don't have any options to pass to ....

If the output filename extension is .docx, a Word document file is produced. This process is facilitated by the rmarkdown package, so this package needs to be installed before attempting to save any table as a .docx document.

Value

The file name (invisibly) if the export process is successful.

Examples

Using a small subset of the gtcars dataset, we can create a gt table with row labels. We'll add a stubhead label with the tab_stubhead() function to describe what is in the stub.

tab_1 <-
  gtcars |>
  dplyr::select(model, year, hp, trq) |>
  dplyr::slice(1:5) |>
  gt(rowname_col = "model") |>
  tab_stubhead(label = "car")

Export the gt table to an HTML file with inlined CSS (which is necessary for including the table as part of an HTML email) using gtsave() and the inline_css = TRUE option.

tab_1 |> gtsave(filename = "tab_1.html", inline_css = TRUE)

By leaving out the inline_css option, we get a more conventional HTML file with embedded CSS styles.

tab_1 |> gtsave(filename = "tab_1.html")

Saving as a PNG file results in a cropped image of an HTML table. The amount of whitespace can be set with the expand option.

tab_1 |> gtsave("tab_1.png", expand = 10)

Any use of the .tex, .ltx, or .rnw will result in the output of a LaTeX document.

tab_1 |> gtsave("tab_1.tex")

With the .rtf extension, we'll get an RTF document.

tab_1 |> gtsave("tab_1.rtf")

With the .docx extension, we'll get a word/docx document.

tab_1 |> gtsave("tab_1.docx")

Function ID

13-1

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other table export functions: as_gtable(), as_latex(), as_raw_html(), as_rtf(), as_word(), extract_body(), extract_cells(), extract_summary()

rstudio/gt documentation built on Dec. 2, 2024, 11:05 a.m.