mccarthy-m-g / gt

Easily generate information-rich, publication-quality tables from R

---

---

---

With the gt package, anyone can make wonderful-looking tables using the R programming language. The gt philosophy: we can construct a wide variety of useful tables with a cohesive set of table parts. These include the table header, the stub, the column labels and spanner column labels, the table body, and the table footer.

It all begins with table data (be it a tibble or a data frame). You then decide how to compose your gt table with the elements and formatting you need for the task at hand. Finally, the table is rendered by printing it at the console, including it in an R Markdown document, or exporting to a file using gtsave(). Currently, gt supports the HTML, LaTeX, and RTF output formats.

---

The gt package is designed to be both straightforward yet powerful. The emphasis is on simple functions for the everyday display table needs. Here is a brief example of how to use gt to create a table from the included sp500 dataset:

library(gt)

# Define the start and end dates for the data range
start_date <- "2010-06-07"
end_date <- "2010-06-14"

# Create a gt table based on preprocessed
# `sp500` table data
sp500 |>
  dplyr::filter(date >= start_date & date <= end_date) |>
  dplyr::select(-adj_close) |>
  gt() |>
  tab_header(
    title = "S&P 500",
    subtitle = glue::glue("{start_date} to {end_date}")
  ) |>
  fmt_currency() |>
  fmt_date(columns = date, date_style = "wd_m_day_year") |>
  fmt_number(columns = volume, suffixing = TRUE)

There are ten datasets provided by gt: countrypops, sza, gtcars, sp500, pizzaplace, exibble, towny, metro, rx_adsl, and rx_addv. They're useful for experimenting with gt’s functions and the package documentation makes extensive use of them in the Examples section within each function's documentation.

Beyond this simple example, there are many functions available in gt for creating super-customized tables. For much more information on these, visit the documentation website.

With the gt Test Drive, you can try gt in the Posit Cloud environment that features the RStudio IDE and a large collection of ready-to-run examples. Visit the publicly available Posit Cloud project and try out the package in your browser. There's no charge to use this platform and you'll learn a lot about what the package can do!

DISCUSSIONS

Let's talk about making tables with gt! There are a few locations where there is much potential for discussion.

One such place is in GitHub Discussions. This discussion board is especially great for Q&A, and many people have had their problems solved in there.

Another fine venue for discussion is in the gt_package Discord server. This is a good option for asking about the development of gt, pitching ideas that may become features, and sharing your table creations!

Finally, there is the gt_package Twitter account. There you'll find tweets about gt (including sneak previews about in-development features) and other table-generation packages.

These are all great places to ask questions about how to use the package, discuss some ideas, engage with others, and much more!

INSTALLATION

The gt package can be installed from CRAN with:

install.packages("gt")

You can also choose to install the development version of gt from GitHub:

devtools::install_github("rstudio/gt")

If you encounter a bug, have usage questions, or want to share ideas to make this package better, please feel free to file an issue.

---

How gt fits in with Other Packages that Generate Display Tables

The gt package joins a burgeoning collection of packages for display table generation. Why another? We feel that there is enough room in this space to innovate further. Here are some of the ways that gt contributes to this ecosystem:

• the interface is high-level and declarative (general instructions versus very specific)
• the formatting options are ‘batteries included’ (scientific notation, uncertainty, ranges, percentages, suffixes, localized currency, dates/times + much more)
• there is excellent, pain-free support for footnotes
• the output is ‘camera-ready’
• multiple output formats are supported with the same declarative interface
• the API closely follows tidyverse conventions by adhering to the tidyverse style guide
• there’s a focus on making the package documentation and examples the best they can be
• rigorous QA/QC measures: high test coverage for automated tests, and thorough manual testing by QA engineers (with every proposed code change)

While gt is trying to do something different with its own interface, it may not suit your specific needs. Here is a listing of other leading table-making R packages, with links to their respective project pages:

• knitr (GITHUB, WEBSITE)
• DT (GITHUB, WEBSITE)
• reactable (GITHUB, WEBSITE)
• flextable (GITHUB, WEBSITE)
• kableExtra (GITHUB, WEBSITE)
• formattable (GITHUB, WEBSITE)
• huxtable (GITHUB, WEBSITE)
• ftextra (GITHUB, WEBSITE)

Packages that use or extend gt

There are several R packages that either use gt to generate tabular outputs or extend gt in amazing ways. Here is a short list of some of these great packages:

• gtsummary (GITHUB, WEBSITE)
• gtExtras (GITHUB, WEBSITE)
• pointblank (GITHUB, WEBSITE)
• tfrmt (GITHUB, WEBSITE)
• gto (GITHUB)

---

Code of Conduct

Please note that the gt project is released with a contributor code of conduct.
By participating in this project you agree to abide by its terms.

📄 License

gt is licensed under the MIT license. See the LICENSE.md file for more details.

© Posit Software, PBC.

🏛️ Governance

This project is primarily maintained by Rich Iannone. Other authors may occasionally assist with some of these duties.

---

---