Chapter 9 The table in its document

A flextable describes a table: its content, its formatting, its widths. It says nothing about how the document that receives it should treat it - whether it may float, whether its header repeats across pages, whether a reader can scroll it horizontally, what a screen reader announces about it.

That is the job of set_table_properties(). Three of its arguments apply to every format (layout, width, align), and the others carry options that only one format understands.

set_table_properties(
  x,
  layout = "fixed", width = 0, align = NULL,
  opts_html = list(), opts_word = list(), opts_pdf = list(),
  word_title = NULL, word_description = NULL
)

Properties set this way are not formatting: a theme function will not overwrite them, and they survive the addition of rows. They can also be set once for the whole document with set_flextable_defaults().

9.1 Common properties

layout and width govern how the width of the table is decided; they are covered with the other sizing functions in 7.2.

align places the table in the page: "left", "center" or "right". It is honoured in Word, HTML and PDF, and ignored in PowerPoint, where the position of the table is the position of its shape.

ft <- qflextable(head(cars))
set_table_properties(ft, align = "center")

speed

dist

4

2

4

10

7

4

7

22

8

16

9

10

9.2 HTML options

9.2.1 A scroll-box for wide or long tables

A table wider than its container overflows the page. scroll puts it in a box the reader can scroll instead.

An empty list gives a horizontal scroll-box as wide as the container:

set.seed(2)
dat <- as.data.frame(setNames(
  lapply(1:14, function(x) rnorm(n = 20)),
  paste0("colname", 1:14)
))

ft_wide <- flextable(dat) |>
  colformat_double(digits = 1) |>
  autofit()

set_table_properties(ft_wide, opts_html = list(scroll = list()))

colname1

colname2

colname3

colname4

colname5

colname6

colname7

colname8

colname9

colname10

colname11

colname12

colname13

colname14

-0.9

2.1

-0.4

-1.8

1.0

1.1

1.2

-0.6

0.4

-1.0

0.3

0.4

-0.1

1.3

0.2

-1.2

-2.0

2.0

-1.7

0.3

0.1

0.4

-0.6

-1.3

-1.0

0.7

2.9

-0.1

1.6

1.6

-0.8

-0.7

-0.5

-0.3

1.7

-0.8

-0.3

0.4

2.9

-0.8

1.2

-0.3

-1.1

2.0

1.9

0.2

-1.4

-0.7

-0.4

0.1

0.4

-1.1

0.2

1.9

0.5

-1.9

-0.1

0.0

0.6

0.5

-2.2

-0.9

-1.0

0.7

-1.3

0.5

-1.0

0.1

0.8

-0.6

0.1

-2.5

2.0

-0.8

1.8

2.0

0.5

-0.7

-0.9

1.2

0.4

0.5

-0.6

-1.4

0.7

0.5

-0.3

-2.0

-0.7

0.9

-0.7

0.7

2.1

0.0

-0.1

-0.1

0.1

1.9

-0.2

-0.6

-0.1

-0.5

-0.3

2.0

0.6

0.5

-2.1

0.5

-0.4

0.9

0.3

0.5

2.0

0.8

-0.2

0.1

-0.4

-0.4

-1.7

-0.8

-1.2

-0.7

0.6

-0.4

-0.5

0.5

-0.1

0.3

-1.2

-0.9

0.4

-0.4

-1.7

-1.0

1.0

0.5

0.2

2.3

-0.5

-0.0

0.4

0.7

-0.8

-0.9

1.6

-1.0

0.7

1.0

1.1

-1.3

1.0

1.6

0.5

-2.7

1.0

0.3

2.1

0.3

1.7

-0.3

0.3

-0.2

0.8

-0.1

-0.5

-2.0

-0.4

-0.0

-0.4

1.1

-0.6

-0.1

-1.2

0.5

0.9

0.7

0.1

-1.3

1.8

-0.6

-0.2

0.0

-1.0

-0.3

1.3

0.4

-1.4

1.4

-2.0

-0.8

0.3

-0.3

-1.4

-0.0

-0.3

-1.2

1.8

-0.8

-1.0

-0.1

-1.5

0.6

1.2

1.3

-0.9

1.1

0.1

-1.7

0.8

0.3

-2.3

-0.6

-2.0

-0.9

-1.3

0.5

1.2

-1.3

-0.7

0.7

0.5

-1.1

0.5

1.6

0.9

-1.7

-0.3

1.3

2.0

1.2

1.0

0.8

-0.3

-0.4

1.2

-0.6

-0.3

-0.0

0.0

-0.9

0.9

0.8

0.0

1.1

0.8

0.5

-0.9

-0.8

-1.3

0.5

-0.3

1.0

1.0

-0.6

1.1

1.1

-0.8

0.1

2.1

0.3

0.8

-0.9

-1.1

0.1

1.0

-0.4

0.4

-0.2

1.7

-1.4

-0.6

-0.8

-1.5

0.7

-1.6

-0.7

1.7

-0.6

-0.2

0.1

With a height, the box also scrolls vertically. freeze_first_column makes the first column sticky, so the row labels stay visible while the reader scrolls to the right - which is what makes a wide table readable at all:

set_table_properties(
  ft_wide,
  opts_html = list(
    scroll = list(
      height = "300px",
      freeze_first_column = TRUE,
      add_css = "border: 1px solid #CCCCCC;"
    )
  )
)

colname1

colname2

colname3

colname4

colname5

colname6

colname7

colname8

colname9

colname10

colname11

colname12

colname13

colname14

-0.9

2.1

-0.4

-1.8

1.0

1.1

1.2

-0.6

0.4

-1.0

0.3

0.4

-0.1

1.3

0.2

-1.2

-2.0

2.0

-1.7

0.3

0.1

0.4

-0.6

-1.3

-1.0

0.7

2.9

-0.1

1.6

1.6

-0.8

-0.7

-0.5

-0.3

1.7

-0.8

-0.3

0.4

2.9

-0.8

1.2

-0.3

-1.1

2.0

1.9

0.2

-1.4

-0.7

-0.4

0.1

0.4

-1.1

0.2

1.9

0.5

-1.9

-0.1

0.0

0.6

0.5

-2.2

-0.9

-1.0

0.7

-1.3

0.5

-1.0

0.1

0.8

-0.6

0.1

-2.5

2.0

-0.8

1.8

2.0

0.5

-0.7

-0.9

1.2

0.4

0.5

-0.6

-1.4

0.7

0.5

-0.3

-2.0

-0.7

0.9

-0.7

0.7

2.1

0.0

-0.1

-0.1

0.1

1.9

-0.2

-0.6

-0.1

-0.5

-0.3

2.0

0.6

0.5

-2.1

0.5

-0.4

0.9

0.3

0.5

2.0

0.8

-0.2

0.1

-0.4

-0.4

-1.7

-0.8

-1.2

-0.7

0.6

-0.4

-0.5

0.5

-0.1

0.3

-1.2

-0.9

0.4

-0.4

-1.7

-1.0

1.0

0.5

0.2

2.3

-0.5

-0.0

0.4

0.7

-0.8

-0.9

1.6

-1.0

0.7

1.0

1.1

-1.3

1.0

1.6

0.5

-2.7

1.0

0.3

2.1

0.3

1.7

-0.3

0.3

-0.2

0.8

-0.1

-0.5

-2.0

-0.4

-0.0

-0.4

1.1

-0.6

-0.1

-1.2

0.5

0.9

0.7

0.1

-1.3

1.8

-0.6

-0.2

0.0

-1.0

-0.3

1.3

0.4

-1.4

1.4

-2.0

-0.8

0.3

-0.3

-1.4

-0.0

-0.3

-1.2

1.8

-0.8

-1.0

-0.1

-1.5

0.6

1.2

1.3

-0.9

1.1

0.1

-1.7

0.8

0.3

-2.3

-0.6

-2.0

-0.9

-1.3

0.5

1.2

-1.3

-0.7

0.7

0.5

-1.1

0.5

1.6

0.9

-1.7

-0.3

1.3

2.0

1.2

1.0

0.8

-0.3

-0.4

1.2

-0.6

-0.3

-0.0

0.0

-0.9

0.9

0.8

0.0

1.1

0.8

0.5

-0.9

-0.8

-1.3

0.5

-0.3

1.0

1.0

-0.6

1.1

1.1

-0.8

0.1

2.1

0.3

0.8

-0.9

-1.1

0.1

1.0

-0.4

0.4

-0.2

1.7

-1.4

-0.6

-0.8

-1.5

0.7

-1.6

-0.7

1.7

-0.6

-0.2

0.1

height is a number of pixels when numeric, or any valid CSS length when a string. add_css applies to the box, not to the table.

9.2.2 Extra CSS and extra classes

extra_css adds CSS rules next to the table, and extra_class adds class names to its <table> tag. They are the hooks for anything flextable does not express itself, and for integration with the stylesheet of a site.

set_table_properties(
  ft,
  opts_html = list(
    extra_class = "my-report-table",
    extra_css = ".my-report-table caption { font-variant: small-caps; }"
  )
)

speed

dist

4

2

4

10

7

4

7

22

8

16

9

10

Beware that these only reach HTML output: the same table in Word ignores them. Prefer flextable functions whenever they can express the result, so that the table stays identical across formats.

9.3 Word options

ft_w <- set_table_properties(
  ft,
  opts_word = list(
    split = FALSE,
    keep_with_next = TRUE,
    repeat_headers = TRUE
  )
)
  • split: allows Word to break a row across two pages. FALSE, the default, keeps each row whole.
  • keep_with_next: keeps the rows of the table together, so that Word does not break it at all. It is meant for tables shorter than a page; for longer ones, paginate() gives control row by row (see 8).
  • repeat_headers: repeats the header rows at the top of each page the table spans. It is TRUE by default.

9.4 PDF options

The PDF output goes through LaTeX, and several of its options have no equivalent elsewhere.

set_table_properties(
  ft,
  opts_pdf = list(
    tabcolsep = 2,
    arraystretch = 1.5,
    padding_vertical = TRUE,
    float = "none",
    caption_repeat = TRUE,
    footer_repeat = TRUE
  )
)
  • tabcolsep: space between the text and the left and right borders of its cell, for the whole table.
  • arraystretch: height of each row relative to its default height. Its default value is 1.5.
  • padding_vertical: applies padding.top and padding.bottom, which are otherwise ignored. When activating it, arraystretch = 1 is recommended, otherwise the two add up.
  • float: how the table is placed. "none" (the default) puts it after the preceding paragraph; "float" lets LaTeX move it where it fits; "wrap-r", "wrap-l", "wrap-i" and "wrap-o" wrap the text around it, on the right, on the left, on the inside edge near the binding or on the outside edge.
  • caption_repeat and footer_repeat: repeat the caption and the footer on every page the table spans. Both are TRUE by default.
  • fonts_ignore: allows the pdflatex engine, which cannot use system fonts, by ignoring the fonts of the table. Prefer adding latex_engine: xelatex to the document.
  • default_line_color: the default line colour, restored globally once the table is produced.

9.5 Accessibility: alternative text in Word

A screen reader announces a Word table by its title and its description - the fields Word shows under “Alt Text”. Without them, the reader only hears the cells, with no indication of what the table is.

word_title and word_description fill these two fields.

ft <- set_table_properties(
  ft,
  word_title = "Stopping distance by speed",
  word_description = paste(
    "Two columns: speed in miles per hour and the distance in feet",
    "needed to stop. 50 observations from the 1920s."
  )
)

Write the description for someone who cannot see the table: say what the columns are and what the figures mean, not that it is a table with two columns and fifty rows, which the reader already knows.

A caption set with set_caption() is a different thing: it is visible text, read in sequence with the rest of the document. The two are complementary, and a table meant to be accessible wants both.

These two arguments only reach Word output. In HTML, use extra_css and extra_class together with the caption; flextable does not write an aria-describedby attribute. The state of accessible PDF output is discussed in A.

9.6 Setting them once for the whole document

Most of these options can be given to set_flextable_defaults(), so that each table of a document gets it without repeating the call. This is the recommended way to keep a report homogeneous (see 12).

They are passed flat there, without the opts_* wrapper, and the alignment is named table_align:

set_flextable_defaults(
  table.layout = "autofit",
  table_align = "center",
  scroll = list(freeze_first_column = TRUE),
  extra_css = "caption { font-variant: small-caps; }",
  split = FALSE,
  keep_with_next = TRUE,
  tabcolsep = 2,
  arraystretch = 1.5,
  padding_vertical = TRUE,
  float = "none"
)

The options without a default - repeat_headers, extra_class, caption_repeat, footer_repeat, default_line_color, word_title and word_description - have to be set on each table. When the value is the same for the whole document, a post-processing function avoids repeating it; it is called just before the table is printed, and only for the format concerned:

set_flextable_defaults(
  post_process_docx = function(x) {
    set_table_properties(x, opts_word = list(repeat_headers = TRUE))
  }
)

post_process_all applies to every format, and post_process_html, post_process_pdf and post_process_pptx to the other three.