opt_table_font: Options to define font choices for the entire table

In gt: Easily Create Presentation-Ready Display Tables

Options to define font choices for the entire table

Description

opt_table_font() 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 cell_text().

Usage

opt_table_font(
  data,
  font = NULL,
  stack = NULL,
  size = NULL,
  weight = NULL,
  style = NULL,
  color = NULL,
  add = TRUE
)

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.
font	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.
stack	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.
size	Text size ⁠scalar<character|numeric|integer>⁠ // default: NULL (optional) The text size for the entire table can be set by providing a size value. Can be specified as a single-length character vector with units of pixels (e.g., ⁠12px⁠) or as a percentage (e.g., ⁠80%⁠). If provided as a single-length numeric vector, it is assumed that the value is given in units of pixels. The px() and pct() helper functions can also be used to pass in numeric values and obtain values as pixel or percentage units.
weight	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.
style	Text style ⁠scalar<character>⁠ // default: NULL (optional) An option to modify the text style. Can be one of either "normal", "italic", or "oblique".
color	Text color ⁠scalar<character>⁠ // default: NULL (optional) The color option defines the text color used throughout the table. A color name or a hexadecimal color code should be provided.
add	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.

Value

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 google_font(), default_fonts(), and system_fonts() 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"

Examples

Use a subset of the sp500 dataset to create a small gt table. We'll use fmt_currency() to display a dollar sign for the first row of monetary values. 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() |>
  fmt_currency(
    rows = 1,
    use_seps = FALSE
  ) |>
  opt_table_font(
    font = list(
      google_font(name = "Merriweather"),
      "Cochin", "serif"
    )
  )

With the sza dataset we'll create a two-column, eleven-row table. Within opt_table_font(), the stack argument will be supplied with 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 |>
  dplyr::filter(
    latitude == 20 &
      month == "jan" &
      !is.na(sza)
  ) |>
  dplyr::select(-latitude, -month) |>
  gt() |>
  opt_table_font(stack = "rounded-sans") |>
  opt_all_caps()

Function ID

10-12

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 April 12, 2025, 1:26 a.m.