gt Package: Beautiful Publication-Ready Tables in R

The gt package gives you a "grammar of tables" — a layered system for turning any data frame into a polished, publication-ready table with formatted numbers, styled headers, conditional colors, and footnotes, all in a few lines of R code.

How Does gt() Turn a Data Frame into a Table?

Console output is fine for exploration, but reports and papers demand clean formatting. The gt package lets you pipe a data frame straight into a presentation-quality table. Let's see it in action.

The gt() function is the entry point — it takes any data frame and wraps it in a structured table object. From there, you layer on formatting with tab_header(), tab_source_note(), and other functions, just like adding layers in ggplot2.

Now let's add a source note to credit where the data came from. Source notes appear at the bottom of the table and are standard in academic publications.

The tab_source_note() adds a citation at the table footer. You can chain multiple source notes if the data comes from several sources.

How Do You Format Numbers, Currencies, and Percentages?

Raw numbers with many decimal places clutter your tables. The fmt_*() family reformats column values in place — no need to mutate your data first. These functions handle thousands separators, decimal precision, currency symbols, and percentages automatically.

Let's create a summary table and format the numbers for readability.

The fmt_number() function takes a columns argument (supports tidy selection) and decimals to control precision. Notice how different columns get different decimal places — chain multiple fmt_number() calls for this.

Now let's see currency and percentage formatting. These are common in business reports where you need dollar signs and percent symbols.

The fmt_currency() function adds the currency symbol, thousands separators, and two decimal places by default. The fmt_percent() function multiplies by 100 and appends the % sign. Both accept a locale argument for international formatting.

Sometimes your data has missing values or dates that need special handling. The sub_missing() function replaces NA with a custom string, and fmt_date() converts date columns to readable formats.

The sub_missing() function with columns = everything() catches NAs in any column. You can target specific columns and use different replacement text for each.

How Do You Add Headers, Spanners, and Row Groups?

Real-world tables often have hierarchical structure — columns that belong together under a shared label, or rows grouped by category. gt handles both with tab_spanner() for column groups and tab_row_group() for row groups.

Let's group related columns under a spanner label. Spanners add a second header row that visually ties columns together.

Each tab_spanner() call creates a header that spans the specified columns. The cols_label() function renames the individual column headers underneath — use readable names instead of the raw variable names.

Now let's organize rows into groups. This is useful when your table has a categorical variable that defines natural clusters.

The tab_row_group() function filters rows using the rows argument (same syntax as dplyr's filter). Groups appear in the order you define them, with a bold label row separating each group.

How Do You Style Cells with Conditional Formatting?

Plain tables communicate data, but styled tables guide the reader's eye to what matters. The tab_style() function applies CSS-like formatting to specific cells, rows, or columns. You target locations with helper functions like cells_body(), cells_column_labels(), and cells_row_groups().

Let's start by styling the column headers with a bold font and background color.

The tab_style() function takes two main arguments: style (a list of cell formatting rules) and locations (which cells to target). The cell_fill(), cell_text(), and cell_borders() helpers control background color, font properties, and border styles respectively.

Now let's apply conditional formatting — highlighting rows where a value exceeds a threshold. This is one of the most practical uses of tab_style().

Each tab_style() call is independent — you can stack multiple conditional rules. The rows argument accepts any logical expression that references column values, just like dplyr::filter().

For continuous color scales across an entire column, use data_color(). This maps numeric values to a gradient, creating a heatmap effect.

The data_color() function maps the minimum value to the first palette color and the maximum to the last. The palette accepts any hex colors or named R colors. Note the reversed palette for HP — higher horsepower gets a warmer color to signal "more intense."

How Do You Add Footnotes and Source Notes?

Professional tables cite their sources and clarify specific values with footnotes. gt handles both automatically — footnotes get numbered markers, and source notes appear at the table footer.

Each tab_footnote() auto-numbers its marker. You can target column headers with cells_column_labels(), specific body cells with cells_body(), or even the title with cells_title(). The tab_source_note() is separate and always appears last in the footer without a number.

How Do You Apply Themes and Custom Styling?

The default gt table looks clean, but you'll often want a consistent look across all your tables. The opt_stylize() function applies pre-built themes with a single call, while tab_options() gives you fine-grained control over every visual detail.

The opt_stylize() function offers 6 built-in styles (1 through 6) and several color options including "blue", "cyan", "pink", "green", "red", and "gray". Style 1 is subtle, style 6 is bold. Pick one that matches your report's tone.

For full control, tab_options() lets you set individual properties — font family, font size, row padding, border styles, header colors, and more.

That's a lot of options, and tab_options() supports over 100 properties. The ones above cover the most common needs: header styling, column label appearance, row striping, borders, and font sizes.

Let's create that reusable theme and apply it.

Now every table in your report gets the same professional look with a single function call. You can keep the theme function in a shared script and source it across projects.

Practice Exercises

Exercise 1: Formatted Summary Table

Build a summary statistics table from airquality. Group by Month, compute the mean and standard deviation of Ozone (ignore NAs), format all numbers to 1 decimal place, add the title "NYC Air Quality by Month", and include a source note crediting "NY State Dept of Conservation".

Exercise 2: Styled Comparison Table

Create a table from mtcars (first 10 rows) with columns name, mpg, hp, and cyl. Add a spanner "Performance" over mpg and hp. Highlight mpg cells above 20 in green ("#d4edda") and below 16 in red ("#f8d7da"). Apply opt_stylize(style = 1, color = "blue") and add a title.

Exercise 3: Complete Report Table

Build a "report card" table. Create sample data for 6 students with columns: student, subject (Math or Science), score, and grade (A/B/C). Add row groups by subject. Format scores to 0 decimals. Color grade cells — green for A, yellow for B, red for C. Add a footnote on the score column header saying "Out of 100 points". Apply a custom theme.

Putting It All Together

Let's build a polished table from scratch — taking raw mtcars data through the complete gt pipeline: summarise, structure, format, style, annotate, and theme.

This pipeline demonstrates every major gt feature: structural elements (header, spanner, column labels), formatting (decimal precision), styling (conditional fills, color gradients), annotations (footnote, source note), and theming (custom options). Each layer builds on the previous one without modifying the underlying data.

Summary

Here are the key gt functions organized by what they do:

Figure 1: The gt table-building pipeline — raw data flows through structure, formatting, styling, annotation, and theming layers.

References

1. Iannone, R., Cheng, J., Schloerke, B., Hughes, E., Lauer, A., & Seo, J. — gt: Easily Create Presentation-Ready Display Tables. Link
2. gt CRAN documentation. Link
3. Iannone, R. — Introduction to Creating gt Tables. Link
4. Rapp, A. — Creating Beautiful Tables in R with gt. Link
5. Wickham, H., Çetinkaya-Rundel, M., & Grolemund, G. — R for Data Science (2e). O'Reilly (2023). Link
6. R Graph Gallery — gt Package Tutorial. Link
7. gtsummary package — Presentation-Ready Summary Tables. Link

Continue Learning

• Publication-Quality Figures in R — The parent guide on making journal-ready ggplot2 figures with proper fonts, sizes, and color profiles.
• ggplot2 Themes in R — Comprehensive guide to customizing ggplot2's visual appearance with theme elements.
• Statistical Report Writing in R — Build complete reproducible reports combining narrative, code, tables, and figures.