add_header_row: Add a header row with spanning labels

In flextable: Functions for Tabular Reporting

Add a header row with spanning labels

Description

Add a single row to the header where labels can span multiple columns (merged cells) via the colwidths argument.

Labels are associated with a number of columns to merge that default to one if not specified. In this case, you have to make sure that the number of labels is equal to the number of columns displayed.

The function can add only one single row by call.

Labels can also be formatted with as_paragraph().

Usage

add_header_row(x, top = TRUE, values = character(0), colwidths = integer(0))

Arguments

x	a 'flextable' object, see flextable-package to learn how to create 'flextable' object.
top	should the row be inserted at the top or the bottom. Default to TRUE.
values	values to add, a character vector (as header rows contains only character values/columns), a list or a call to as_paragraph().
colwidths	the number of columns used for each label

See Also

flextable(), set_caption()

Other row and column operations: add_body(), add_body_row(), add_footer(), add_footer_lines(), add_footer_row(), add_header(), add_header_lines(), delete_columns(), delete_part(), delete_rows(), paginate(), separate_header(), set_header_footer_df, set_header_labels(), split_columns(), split_rows(), split_to_pages()

Examples

library(flextable)

ft01 <- fp_text_default(color = "red")
ft02 <- fp_text_default(color = "orange")

pars <- as_paragraph(
  as_chunk(c("(1)", "(2)"), props = ft02), " ",
  as_chunk(c(
    "My tailor is rich",
    "My baker is rich"
  ), props = ft01)
)

ft_1 <- flextable(head(mtcars))
ft_1 <- add_header_row(ft_1,
  values = pars,
  colwidths = c(5, 6), top = FALSE
)
ft_1 <- add_header_row(ft_1,
  values = pars,
  colwidths = c(3, 8), top = TRUE
)
ft_1

ft_2 <- flextable(head(airquality))
ft_2 <- add_header_row(ft_2,
  values = c("Measure", "Time"),
  colwidths = c(4, 2), top = TRUE
)
ft_2 <- theme_box(ft_2)
ft_2

flextable documentation built on June 2, 2026, 9:08 a.m.