Format values as a percentage

With numeric values in a gt table, we can perform percentage-based formatting. It is assumed the input numeric values are proportional values and, in this case, the values will be automatically multiplied by 100 before decorating with a percent sign (the other case is accommodated though setting the scale_values to FALSE) For more control over percentage formatting, we can use the following options:

percent sign placement: the percent sign can be placed after or before the values and a space can be inserted between the symbol and the value.
decimals: choice of the number of decimal places, option to drop trailing zeros, and a choice of the decimal symbol
digit grouping separators: options to enable/disable digit separators and provide a choice of separator symbol
pattern: option to use a text pattern for decoration of the formatted values
locale-based formatting: providing a locale ID will result in number formatting specific to the chosen locale

fmt_percent(
  data,
  columns,
  rows = NULL,
  decimals = 2,
  drop_trailing_zeros = FALSE,
  drop_trailing_dec_mark = TRUE,
  scale_values = TRUE,
  use_seps = TRUE,
  pattern = "{x}",
  sep_mark = ",",
  dec_mark = ".",
  incl_space = FALSE,
  placement = "right",
  locale = NULL
)

Arguments

data	A table object that is created using the `gt()` function.
columns	The columns to format. Can either be a series of column names provided in `vars()`, a vector of column indices, or a helper function focused on selections. The select helper functions are: `starts_with()`, `ends_with()`, `contains()`, `matches()`, `one_of()`, and `everything()`.
rows	Optional rows to format. Not providing any value results in all rows in `columns` being formatted. Can either be a vector of row captions provided `c()`, a vector of row indices, or a helper function focused on selections. The select helper functions are: `starts_with()`, `ends_with()`, `contains()`, `matches()`, `one_of()`, and `everything()`. We can also use expressions to filter down to the rows we need (e.g., `[colname_1] > 100 & [colname_2] < 50`).
decimals	An option to specify the exact number of decimal places to use. The default number of decimal places is `2`.
drop_trailing_zeros	A logical value that allows for removal of trailing zeros (those redundant zeros after the decimal mark).
drop_trailing_dec_mark	A logical value that determines whether decimal marks should always appear even if there are no decimal digits to display after formatting (e.g, `23` becomes `23.`). The default for this is `TRUE`, which means that trailing decimal marks are not shown.
scale_values	Should the values be scaled through multiplication by 100? By default this is `TRUE` since the expectation is that normally values are proportions. Setting to `FALSE` signifies that the values are already scaled and require only the percent sign when formatted.
use_seps	An option to use digit group separators. The type of digit group separator is set by `sep_mark` and overridden if a locale ID is provided to `locale`. This setting is `TRUE` by default.
pattern	A formatting pattern that allows for decoration of the formatted value. The value itself is represented by `{x}` and all other characters are taken to be string literals.
sep_mark	The mark to use as a separator between groups of digits (e.g., using `sep_mark = ","` with `1000` would result in a formatted value of `1,000`).
dec_mark	The character to use as a decimal mark (e.g., using `dec_mark = ","` with `0.152` would result in a formatted value of `0,152`).
incl_space	An option for whether to include a space between the value and the percent sign. The default is to not introduce a space character.
placement	The placement of the percent sign. This can be either be `right` (the default) or `left`.
locale	An optional locale ID that can be used for formatting the value according the locale's rules. Examples include `"en_US"` for English (United States) and `"fr_FR"` for French (France). The use of a valid locale ID will override any values provided in `sep_mark` and `dec_mark`. We can use the `info_locales()` function as a useful reference for all of the locales that are supported.

Value

An object of class gt_tbl.

Details

Targeting of values is done through columns and additionally by rows (if nothing is provided for rows then entire columns are selected). A number of helper functions exist to make targeting more effective. Conditional formatting is possible by providing a conditional expression to the rows argument. See the Arguments section for more information on this.

Figures

Function ID

3-3

Examples