Format values as currencies

With numeric values in a gt table, we can perform currency-based formatting. This function supports both automatic formatting with a three-letter or numeric currency code. We can also specify a custom currency that is formatted according to the output context with the currency() helper function. Numeric formatting facilitated through the use of a locale ID. We have fine control over the conversion from numeric values to currency values, where we could take advantage of the following options:

the currency: providing a currency code or common currency name will procure the correct currency symbol and number of currency subunits; we could also use the currency() helper function to specify a custom currency
currency symbol placement: the currency symbol can be placed before or after the values
decimals/subunits: choice of the number of decimal places, and a choice of the decimal symbol, and an option on whether to include or exclude the currency subunits (decimal portion)
negative values: choice of a negative sign or parentheses for values less than zero
digit grouping separators: options to enable/disable digit separators and provide a choice of separator symbol
scaling: we can choose to scale targeted values by a multiplier value
large-number suffixing: larger figures (thousands, millions, etc.) can be autoscaled and decorated with the appropriate suffixes
pattern: option to use a text pattern for decoration of the formatted currency values
locale-based formatting: providing a locale ID will result in currency formatting specific to the chosen locale

We can use the info_currencies() function for a useful reference on all of the possible inputs to the currency argument.

fmt_currency(
  data,
  columns,
  rows = NULL,
  currency = "USD",
  use_subunits = TRUE,
  accounting = FALSE,
  decimals = NULL,
  drop_trailing_dec_mark = TRUE,
  use_seps = TRUE,
  scale_by = 1,
  suffixing = FALSE,
  pattern = "{x}",
  sep_mark = ",",
  dec_mark = ".",
  placement = "left",
  incl_space = FALSE,
  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`).
currency	The currency to use for the numeric value. This input can be supplied as a 3-letter currency code (e.g., `"USD"` for U.S. Dollars, `"EUR"` for the Euro currency). Use `info_currencies()` to get an information table with all of the valid currency codes and examples of each. Alternatively, we can provide a common currency name (e.g., `"dollar"`, `"pound"`, `"yen"`, etc.) to simplify the process. Use `info_currencies()` with the `type == "symbol"` option to view an information table with all of the supported currency symbol names along with examples. We can also use the `currency()` helper function to specify a custom currency, where the string could vary across output contexts. For example, using `currency(html = "&fnof;", default = "f")` would give us a suitable glyph for the Dutch guilder in an HTML output table, and it would simply be the letter "f" in all other output contexts). Please note that `decimals` will default to `2` when using the `currency()` helper function. If nothing is provided to `currency` then `"USD"` (U.S. dollars) will be used.
use_subunits	An option for whether the subunits portion of a currency value should be displayed. By default, this is `TRUE`.
accounting	An option to use accounting style for currency values. With `FALSE` (the default), negative values will be shown with a minus sign. Using `accounting = TRUE` will put negative values in parentheses.
decimals	An option to specify the exact number of decimal places to use. The default number of decimal places is `2`.
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.
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.
scale_by	A value to scale the input. The default is `1.0`. All numeric values will be multiplied by this value first before undergoing formatting. This value will be ignored if using any of the `suffixing` options (i.e., where `suffixing` is not set to `FALSE`).
suffixing	An option to scale and apply suffixes to larger numbers (e.g., `1924000` can be transformed to `1.92M`). This option can accept a logical value, where `FALSE` (the default) will not perform this transformation and `TRUE` will apply thousands (`K`), millions (`M`), billions (`B`), and trillions (`T`) suffixes after automatic value scaling. We can also specify which symbols to use for each of the value ranges by using a character vector of the preferred symbols to replace the defaults (e.g., `c("k", "Ml", "Bn", "Tr")`). Including `NA` values in the vector will ensure that the particular range will either not be included in the transformation (e.g, `c(NA, "M", "B", "T")` won't modify numbers in the thousands range) or the range will inherit a previous suffix (e.g., with `c("K", "M", NA, "T")`, all numbers in the range of millions and billions will be in terms of millions). Any use of `suffixing` (where it is not set expressly as `FALSE`) means that any value provided to `scale_by` will be ignored.
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`).
placement	The placement of the currency symbol. This can be either be `left` (the default) or `right`.
incl_space	An option for whether to include a space between the value and the currency symbol. The default is to not introduce a space character.
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-4

Examples