wb_add_font: Modify font properties in a cell region

In openxlsx2: Read, Write and Edit 'xlsx' Files

Modify font properties in a cell region

Description

The wb_add_font() function provides granular control over the visual appearance of text within a specified cell region. While other styling functions include basic font options, wb_add_font() exposes the full range of font attributes supported by the OpenXML specification, allowing for precise adjustments to typeface, sizing, color, and emphasis.

Usage

wb_add_font(
  wb,
  sheet = current_sheet(),
  dims = "A1",
  name = "Aptos Narrow",
  color = wb_color(hex = "FF000000"),
  size = "11",
  bold = "",
  italic = "",
  outline = "",
  strike = "",
  underline = "",
  charset = "",
  condense = "",
  extend = "",
  family = "",
  scheme = "",
  shadow = "",
  vert_align = "",
  update = FALSE,
  ...
)

Arguments

wb	A wbWorkbook object.
sheet	The name or index of the worksheet. Defaults to the current sheet.
dims	A character string defining the cell range (e.g., "A1:K1").
name	Character; the font name. Defaults to "Aptos Narrow".
color	A wb_color() object or hex string defining the font color. Defaults to black ("FF000000").
size	Numeric; the font size. Defaults to 11.
bold	Logical; applies bold formatting if TRUE.
italic	Logical; applies italic formatting if TRUE.
outline	Logical; applies an outline effect to the text.
strike	Logical; applies a strikethrough effect.
underline	Character; the underline style, such as "single" or "double".
charset	Character; the character set ID. See fmt_txt() for details.
condense	Logical; whether the font should be condensed.
extend	Logical; whether the font should be extended.
family	Character; the font family index (e.g., "1" for Roman, "2" for Swiss).
scheme	Character; the font scheme. One of "minor", "major", or "none".
shadow	Logical; applies a shadow effect to the text.
vert_align	Character; vertical alignment. Options are "baseline", "superscript", or "subscript".
update	Logical or character vector. Controls whether to overwrite the entire font style or only update specific properties.
...	Additional arguments.

Details

This function operates on the font node of a cell's style. It is particularly powerful when used with the update argument, which allows users to modify specific attributes (like color) while preserving other existing font properties (like bold or font name).

For common tasks, adjusting name, size, and color is sufficient. However, the function also supports advanced properties like vert_align (for subscripts/superscripts), family (font categories), and scheme (theme-based font sets).

Note on Updates:

• If update = FALSE (default), the function applies the new font definition as a complete replacement for the existing font style.

• If update is a character vector (e.g., c("color", "size")), only those specific attributes are modified, and all other existing font properties are retained.

• Setting update = NULL removes the custom font style entirely, reverting the cells to the workbook's default font.

Value

The wbWorkbook object, invisibly.

A wbWorkbook, invisibly

Notes

• This function modifies the cell-level style and does not alter rich text strings created with fmt_txt().

• Font styles are pooled in the workbook's style manager to ensure efficiency and XML compliance.

See Also

Other styles: wb_add_border(), wb_add_cell_style(), wb_add_fill(), wb_add_named_style(), wb_add_numfmt(), wb_cell_style

Examples

 wb <- wb_workbook()
 wb <- wb_add_worksheet(wb, "S1")
 wb <- wb_add_data(wb, "S1", mtcars)
 wb <- wb_add_font(wb, "S1", "A1:K1", name = "Arial", color = wb_color(theme = "4"))
# With chaining
 wb <- wb_workbook()$add_worksheet("S1")$add_data("S1", mtcars)
 wb$add_font("S1", "A1:K1", name = "Arial", color = wb_color(theme = "4"))

# Update the font color
 wb$add_font("S1", "A1:K1", color = wb_color("orange"), update = c("color"))

openxlsx2 documentation built on Feb. 21, 2026, 9:07 a.m.