set_caption()

Set a caption for a flextable, with optional auto-numbering, Word style, and HTML formatting.

set_caption() attaches a caption to a flextable. When the output is Word, the caption is associated with a paragraph style and can use auto-numbering. When the output is HTML, CSS classes can be applied. PowerPoint ignores captions.

In Quarto documents, captions and cross-references are managed by Quarto, not flextable. set_caption() settings are overridden by tbl-cap and label chunk options.

Function signature

set_caption(
  x,
  caption = NULL,
  autonum = NULL,
  word_stylename = "Table Caption",
  fp_p = fp_par(padding = 3),
  align_with_table = TRUE,
  html_classes = NULL,
  html_escape = TRUE
)

Parameters

x · flextable · required

A flextable object.

caption · string | paragraph

The caption text. Either a plain character string or a call to as_paragraph() for formatted content (bold, italic, mixed styles, images, or equations). Plain strings do not support Markdown syntax.

autonum · run_autonum

An auto-numbering sequence object created by officer::run_autonum(). Affects Word output (defines the Word auto-number) and HTML/PDF output (provides the bookmark identifier). When provided, the caption is preceded by an auto-number sequence.

word_stylename · string · default: "Table Caption"

Word paragraph style name to associate with the caption. Available style names can be retrieved with officer::styles_info(). Alias: style (deprecated).

fp_p · fp_par · default: "fp_par(padding = 3)"

Paragraph formatting properties from officer::fp_par(). Applied to HTML and Word outputs when possible.

align_with_table · logical · default: "TRUE"

If TRUE, the caption alignment follows the flextable alignment. If FALSE, alignment is taken from fp_p directly.

html_classes · character

One or more CSS class names to apply to the caption element in HTML output.

html_escape · logical · default: "TRUE"

If TRUE, HTML entities in the caption are escaped so the caption is safe to use as text or an attribute value in an HTML document.

Return value

The modified flextable object.

Examples

Simple string caption:

ft <- flextable(head(iris))
ft <- set_caption(ft, "my caption")
ft

Auto-numbered caption for Word:

library(officer)
autonum <- run_autonum(seq_id = "tab", bkm = "mtcars")
ft <- flextable(head(mtcars))
ft <- set_caption(ft, caption = "mtcars data", autonum = autonum)
ft

Formatted caption using as_paragraph():

library(officer)
ft <- flextable(head(cars))
ft <- set_caption(
  ft,
  as_paragraph(
    as_chunk("Table: ", props = fp_text_default(bold = TRUE)),
    as_chunk("cars data", props = fp_text_default(font.family = "Cambria"))
  ),
  word_stylename = "Table Caption"
)
ft

R Markdown chunk options

You can set captions via knitr chunk options instead of calling set_caption() directly:

#| tab.id: bookmark_id
#| tab.cap: caption text
flextable(head(cars))

Available chunk options include:

Option	Description
tab.id	Caption ID or bookmark
tab.cap	Caption text
tab.cap.style	Word style name for the caption
tab.topcaption	Display caption above the table (TRUE)
tab.lp	Caption sequence identifier (default "tab:")
tab.cap.pre	Prefix before auto-number (default "Table ")
tab.cap.sep	Separator after auto-number (default " :")

See also

• officer::run_autonum() — create auto-numbering sequences
• officer::fp_par() — paragraph formatting properties
• as_paragraph() — build formatted captions