opt_table_font: Options to define font choices for the entire table

View source: R/opts.R

opt_table_fontR Documentation

Options to define font choices for the entire table


The opt_table_font() function makes it possible to define fonts used for an entire gt table. Any font names supplied in font will (by default, with add = TRUE) be placed before the names present in the existing font stack (i.e., they will take precedence). You can choose to base the font stack on those provided by system_fonts() by providing a valid keyword for a themed set and optionally prepending font values to that.

Take note that you could still have entirely different fonts in specific locations of the table. For that you would need to use tab_style() or tab_style_body() in conjunction with the cell_text() helper function.


  font = NULL,
  stack = NULL,
  weight = NULL,
  style = NULL,
  add = TRUE



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.


Default table fonts

⁠vector<character>|list|obj:<font_css>⁠ // default: NULL (optional)

One or more font names available as system or web fonts. These can be combined with a c() or a list(). To choose fonts from the Google Fonts service, we can call the google_font() helper function.


Name of font stack

⁠scalar<character>⁠ // default: NULL (optional)

A name that is representative of a font stack (obtained via internally via the system_fonts() helper function). If provided, this new stack will replace any defined fonts and any font values will be prepended.


Text weight

⁠scalar<character|numeric|integer>⁠ // default: NULL (optional)

Option to set the weight of the font. Can be a text-based keyword such as "normal", "bold", "lighter", "bolder", or, a numeric value between 1 and 1000, inclusive. Please note that typefaces have varying support for the numeric mapping of weight.


Text style

⁠scalar<character>⁠ // default: NULL (optional)

An option to modify the text style. Can be one of either "normal", "italic", or "oblique".


Add to existing fonts

⁠scalar<logical>⁠ // default: TRUE

Should fonts be added to the beginning of any already-defined fonts for the table? By default, this is TRUE and is recommended since those fonts already present can serve as fallbacks when everything specified in font is not available. If a stack is provided, then add will automatically set to FALSE.


An object of class gt_tbl.

Possibilities for the font argument

We have the option to supply one or more font names for the font argument. They can be enclosed in c() or a list(). You can generate this list or vector with a combination of font names, and you can freely use the google_font(), default_fonts(), and system_fonts() functions to help compose your font family.

Possibilities for the stack argument

There are several themed font stacks available via the system_fonts() helper function. That function can be used to generate all or a segment of a vector supplied to the font argument. However, using the stack argument with one of the 15 keywords for the font stacks available in system_fonts(), we could be sure that the typeface class will work across multiple computer systems. Any of the following keywords can be used:

  • "system-ui"

  • "transitional"

  • "old-style"

  • "humanist"

  • "geometric-humanist"

  • "classical-humanist"

  • "neo-grotesque"

  • "monospace-slab-serif"

  • "monospace-code"

  • "industrial"

  • "rounded-sans"

  • "slab-serif"

  • "antique"

  • "didone"

  • "handwritten"


Use a subset of the sp500 dataset to create a small gt table. We'll use the fmt_currency() function to display a dollar sign for the first row of monetary values. Then, set a larger font size for the table and use the "Merriweather" font (from Google Fonts, via google_font()) with two system font fallbacks ("Cochin" and the generic "serif").

sp500 |>
  dplyr::slice(1:10) |>
  dplyr::select(-volume, -adj_close) |>
  gt() |>
    rows = 1,
    use_seps = FALSE
  ) |>
    font = list(
      google_font(name = "Merriweather"),
      "Cochin", "serif"
This image of a table was generated from the first code example in the `opt_table_font()` help file.

Use the sza dataset to create an eleven-row table, two-column table. Within opt_table_font(), use the stack argument to define the use of the "rounded-sans" font stack. This sets up a family of fonts with rounded, curved letterforms that should be locally available in different computing environments.

sza |>
    latitude == 20 &
      month == "jan" &
  ) |>
  dplyr::select(-latitude, -month) |>
  gt() |>
  opt_table_font(stack = "rounded-sans") |>
This image of a table was generated from the second code example in the `opt_table_font()` help file.

Function ID


Function Introduced

v0.2.2 (August 5, 2020)

See Also

Other table option functions: opt_align_table_header(), opt_all_caps(), opt_css(), opt_footnote_marks(), opt_footnote_spec(), opt_horizontal_padding(), opt_interactive(), opt_row_striping(), opt_stylize(), opt_table_lines(), opt_table_outline(), opt_vertical_padding()

gt documentation built on Oct. 7, 2023, 9:07 a.m.