xlr_format: Specify formatting options for xlr_* types

In xlr: Create Table Summaries and Export Neat Tables to 'Excel'

Specify formatting options for ⁠xlr_*⁠ types

Description

This function is a utility to work with openxlxs's createStyle, and work with styles between them. xlr_format_numeric() is an alias for xlr_format() but with different default values.

Usage

xlr_format(
  font_size = 11,
  font_colour = "black",
  font = "calibri",
  text_style = NULL,
  border = NULL,
  border_colour = "black",
  border_style = "thin",
  background_colour = NULL,
  halign = "left",
  valign = "top",
  wrap_text = FALSE,
  text_rotation = 0L,
  indent = 0L
)

xlr_format_numeric(
  font_size = 11,
  font_colour = "black",
  font = "calibri",
  text_style = NULL,
  border = NULL,
  border_colour = "black",
  border_style = "thin",
  background_colour = NULL,
  halign = "right",
  valign = "bottom",
  wrap_text = FALSE,
  text_rotation = 0L,
  indent = 0L
)

Arguments

font_size	A numeric. The font size, must be greater than 0.
font_colour	String. The colour of text in the cell. Must be one of colours() or a valid hex colour beginning with "#".
font	String. The name of a font. This is not validated.
text_style	the text styling. You can pass a vector of text decorations or a single string. The options for text style are "bold", "strikeout", "italic", "underline","underline2" (double underline), "accounting" (accounting underline), "accounting2" (double accounting underline). See Details.
border	the cell border. You can pass a vector of "top", "bottom", "left", "right" or a single string to set the borders that you want.
border_colour	Character. The colour of border. Must be the same length as the number of sides specified in border. Each element must be one of colours() or a valid hex colour beginning with "#".
border_style	Border line style vector the same length as the number of sides specified in border. The list of styles are "none", "thin", "medium", "dashed", "dotted", "thick", "double", "hair", "⁠mediumDashed"⁠, "dashDot", "mediumDashDot", "dashDotDot", "mediumDashDot", "dastDotDot", "mediumDashDotDot", "slantDashDosh". See createStyle for more details.
background_colour	Character. Set the background colour for the cell. Must be one of colours() or a valid hex colour beginning with "#".
halign	the horizontal alignment of cell contents. Must be either "left", "right", "center" or "⁠justify"⁠.
valign	the vertical alignment of cell contents. Must be either "top", "center", or "bottom".
wrap_text	Logical. If TRUE cell contents will rap to fit in the column.
text_rotation	Integer. Rotation of text in degrees. Must be an integer between -90 and 90.
indent	Integer. The number of indent positions, must be an integer between 0 and 250.

Details

Text styling

For text styling you can pass either one of the options or options in a vector. For example if you would like to have text that is bold and italised then set:

fmt <- xlr_format(text_style = c("bold", "italic"))

If you would like to the text to be only bold then:

fmt <- xlr_format(text_style = "bold")

Border styling

The three arguments to create border styling are border, border_colour, and border_style. They each take either a vector, where you specify to change what borders to have in each cell and what they look like. To specify that you want a border around a cell, use border, you need to pass a vector of what sides you want to have a border (or a single element if it's only one side). For example:

• "top" the top border

• "left" the left border

• c("bottom", "right") the top and bottom border

• c("left", "right", "bottom") the left, right and bottom borders

• c("top","right","bottom","left") the borders for all sides of the cells

Based on this you can use border_colour to set the border colours. If you want all the same border colour, just pass a character representing the colour you want (e.g. set border_colour = "blue" if you'd like all borders to be blue). Alternatively you can pass a vector the same length as the vector that you passed to border, with the location specifying the colour. For example, if you set:

fmt <- xlr_format(border = c("left", "top"),
                    border_colour = c("blue","red"))

the top border will be red, and the left border will be blue. You set the pattern in the same way for border_style. Alternatively if you only wanted it to be dashed with default colours. You'd set:

fmt <- xlr_format(border = c("left", "top"),
                  border_style = "dashed")

Value

a xlr_format S3 class.

See Also

• is_xlr_format() to test if an R object is a xlr_format

• xlr_table() to use xlr formats

Examples

library(xlr)
# You can initialise a xlr_format, it comes with a list of defaults
bf <- xlr_format()
# It outputs what the style looks like
bf
# You can update the format by defining a new format
bf <- xlr_format(font_size = 11,
                  # not that font is not validated
                  font = "helvetica")
# The main use of xlr_format is to change the format of a vector of
# a xlr type
bd <- xlr_numeric(1:200,
                  dp = 1,
                  style = bf)
# You can also use it to change the styles of an xlr_table, this only
# affect the format in `Excel`
bt <- xlr_table(mtcars, "A clever title", "A useful footnote")
bt <- bt |>
      update_theme(footnote_format = xlr_format(font_size = 7))

xlr documentation built on April 3, 2025, 6:07 p.m.