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 isTRUEby 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: appliespadding.topandpadding.bottom, which are otherwise ignored. When activating it,arraystretch = 1is 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_repeatandfooter_repeat: repeat the caption and the footer on every page the table spans. Both areTRUEby default. -
fonts_ignore: allows thepdflatexengine, which cannot use system fonts, by ignoring the fonts of the table. Prefer addinglatex_engine: xelatexto 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_cssandextra_classtogether with the caption; flextable does not write anaria-describedbyattribute. 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.