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

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.

Usage

opt_table_font(
  data,
  font = NULL,
  stack = NULL,
  weight = NULL,
  style = 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.
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".
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 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"

Examples

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() |>
  fmt_currency(
    rows = 1,
    use_seps = FALSE
  ) |>
  opt_table_font(
    font = list(
      google_font(name = "Merriweather"),
      "Cochin", "serif"
    )
  )

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 |>
  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 Oct. 7, 2023, 9:07 a.m.