# Format content

By default, the displayed content of each cell will be the result of a simple formatting. The content can also be composed as the result of a concatenation of several chunks.

There are formatter functions to define how columns content will be display (e.g. to define the number of decimal). This is a column-wise operation.

User can also have more control over displayed content by using function compose. The function enable to define the elements composing the paragraph and their respective formats. It can also be used to mix text chunks and images.

## Simple functions for formatting content

Theses are high level functions that should satisfy most of the usual needs. They can be used to define the formatting of one or more columns and eventually on a subset of rows.

Each accept a prefix and suffix argument that can be used to add a currency symbol for example. Also they all have na_str argument (defaut to ""), the string to use when data are not available.

• colformat_num() with arguments digits and big.mark
• colformat_int() with arguments big.mark
• colformat_char()
dat <- head(mtcars, n = 10)
dat[3:7, 1] <- NA
dat[, 2] <- dat[, 6] * 1000000

ft <- flextable(dat)
ft
 mpg cyl disp hp drat wt qsec vs am gear carb 21.0 2620000 160.0 110 3.90 2.620 16.46 0 1 4 4 21.0 2875000 160.0 110 3.90 2.875 17.02 0 1 4 4 NA 2320000 108.0 93 3.85 2.320 18.61 1 1 4 1 NA 3215000 258.0 110 3.08 3.215 19.44 1 0 3 1 NA 3440000 360.0 175 3.15 3.440 17.02 0 0 3 2 NA 3460000 225.0 105 2.76 3.460 20.22 1 0 3 1 NA 3570000 360.0 245 3.21 3.570 15.84 0 0 3 4 24.4 3190000 146.7 62 3.69 3.190 20.00 1 0 4 2 22.8 3150000 140.8 95 3.92 3.150 22.90 1 0 4 2 19.2 3440000 167.6 123 3.92 3.440 18.30 1 0 4 4
num_keys <- c("mpg", "disp", "drat", "wt", "qsec")
int_keys <- c("cyl", "hp", "vs", "am", "gear", "carb")

ft <- colformat_num(x = ft, col_keys = num_keys, big.mark = ",", digits = 2, na_str = "missing")
#> Warning in colformat_num.flextable(x = ft, col_keys = num_keys, big.mark =
#> ",", : argument col_keys is deprecated in favor of argument j
ft <- colformat_int(x = ft, col_keys = int_keys, big.mark = ",")
#> Warning in colformat_int.flextable(x = ft, col_keys = int_keys, big.mark = ","):
#> argument col_keys is deprecated in favor of argument j
autofit(ft)
 mpg cyl disp hp drat wt qsec vs am gear carb 21.00 2,620,000 160.00 110 3.90 2.62 16.46 0 1 4 4 21.00 2,875,000 160.00 110 3.90 2.88 17.02 0 1 4 4 missing 2,320,000 108.00 93 3.85 2.32 18.61 1 1 4 1 missing 3,215,000 258.00 110 3.08 3.21 19.44 1 0 3 1 missing 3,440,000 360.00 175 3.15 3.44 17.02 0 0 3 2 missing 3,460,000 225.00 105 2.76 3.46 20.22 1 0 3 1 missing 3,570,000 360.00 245 3.21 3.57 15.84 0 0 3 4 24.40 3,190,000 146.70 62 3.69 3.19 20.00 1 0 4 2 22.80 3,150,000 140.80 95 3.92 3.15 22.90 1 0 4 2 19.20 3,440,000 167.60 123 3.92 3.44 18.30 1 0 4 4

Their names is col_format_* as the first version was not working with rows subset. This limitation is no more true and the functions should then be named format_int, format_num… as they can operate on rows and columns.

## set_formatter function

It is possible to define the functions that will be used to format the data.frame values into strings. set_formatter set column formatter functions.

ft <- flextable(head(mtcars, n = 10 ),
col_keys = c("gear", "mpg", "qsec"))
ft <- set_formatter(ft,
mpg = function(x) sprintf("%.04f", x),
gear = function(x) sprintf("%.0f gears", x)
)
ft <- theme_booktabs(ft)
ft <- autofit(ft)
ft
 gear mpg qsec 4 gears 21.0000 16.46 4 gears 21.0000 17.02 4 gears 22.8000 18.61 3 gears 21.4000 19.44 3 gears 18.7000 17.02 3 gears 18.1000 20.22 3 gears 14.3000 15.84 4 gears 24.4000 20.00 4 gears 22.8000 22.90 4 gears 19.2000 18.30

## compose function

### Usage

flextable content can be defined with function compose.

It lets user control the formated content at the cell level of the table. It is possible to define a content for a row subset and a column as well as on the whole column. One can mix images and text (but not with PowerPoint because PowerPoint can not do it).

Below the starting point of next illustrations:

myft <- flextable( head(mtcars),
col_keys = c("am", "separator", "gear", "mpg", "drat", "qsec" ))
myft <- bold(myft, part = "header")
myft <- border(myft, border = fp_border( width = 0),
border.top = fp_border(), border.bottom = fp_border(),
part = "all")
myft <- align(myft, align = "right", part = "all" )
myft <- border(myft, j = ~ separator, border = fp_border(width=0), part = "all")
myft <- width(myft, j = ~ separator, width = .1)
myft
 am gear mpg drat qsec 1 4 21.0 3.90 16.46 1 4 21.0 3.90 17.02 1 4 22.8 3.85 18.61 0 3 21.4 3.08 19.44 0 3 18.7 3.15 17.02 0 3 18.1 2.76 20.22

The function requires a call to as_paragraph which will concatenate text or images chunks as a paragraph.

The following example shows how to control the format of displayed values and how to associate them with specific text formatting properties (bold red text):

myft <- compose(
myft, j = "mpg",
value = as_paragraph(
"mpg value is ",
as_chunk(sprintf("%.01f", mpg), props = fp_text(color = "red", bold = TRUE) ) )
)
myft <- autofit(myft)
myft
 am gear mpg drat qsec 1 4 mpg value is 21.0 3.90 16.46 1 4 mpg value is 21.0 3.90 17.02 1 4 mpg value is 22.8 3.85 18.61 0 3 mpg value is 21.4 3.08 19.44 0 3 mpg value is 18.7 3.15 17.02 0 3 mpg value is 18.1 2.76 20.22

With that system, it’s easy to concatenate multiple values:

myft <- compose(
myft, j = "mpg",
value = as_paragraph(
"mpg value is ",
as_chunk(sprintf("%.01f", mpg), props = fp_text(color = "red", bold = TRUE) ),
" with ",
as_chunk(sprintf("# %.0f", carb), props = fp_text(color = "gray", italic = TRUE) )
)
)

myft <- autofit(myft)
myft
 am gear mpg drat qsec 1 4 mpg value is 21.0 with # 4 3.90 16.46 1 4 mpg value is 21.0 with # 4 3.90 17.02 1 4 mpg value is 22.8 with # 1 3.85 18.61 0 3 mpg value is 21.4 with # 1 3.08 19.44 0 3 mpg value is 18.7 with # 2 3.15 17.02 0 3 mpg value is 18.1 with # 1 2.76 20.22

Or to define specific title headers:

myft <- compose(
myft, j = "mpg", part = "header",
value = as_paragraph(
"Miles/(US) gallon ",
as_chunk("* with num of carb.", props = fp_text(color = "gray", vertical.align = "superscript") )
)
)

myft <- autofit(myft)
myft
 am gear Miles/(US) gallon * with num of carb. drat qsec 1 4 mpg value is 21.0 with # 4 3.90 16.46 1 4 mpg value is 21.0 with # 4 3.90 17.02 1 4 mpg value is 22.8 with # 1 3.85 18.61 0 3 mpg value is 21.4 with # 1 3.08 19.44 0 3 mpg value is 18.7 with # 2 3.15 17.02 0 3 mpg value is 18.1 with # 1 2.76 20.22

Note that compose is not appending but is replacing the content.

### Limitation for PowerPoint

Using images in flextable is not supported when output format is PowerPoint. This is not a choice nor a unimplemented feature. This is because PowerPoint is not able to embed images in a table cell. That’s a PowerPoint limitation.

If beeing able to display images in PowerPoint table is important to you, you can use the plot function or the save_as_image and embed the result in the PowerPoint. You will of course loose ability to edit the table in PowerPoint.

### Images

Function compose supports images insertion. Use function as_image in as_paragraph call:

img.file <- file.path( R.home("doc"), "html", "logo.jpg" )

myft <- compose( myft, i = ~ qsec > 18, j = "qsec",
value = as_paragraph(as_image( src = img.file, width = .20, height = .15))
)
myft <- autofit(myft)
myft
 am gear Miles/(US) gallon * with num of carb. drat qsec 1 4 mpg value is 21.0 with # 4 3.90 16.46 1 4 mpg value is 21.0 with # 4 3.90 17.02 1 4 mpg value is 22.8 with # 1 3.85 0 3 mpg value is 21.4 with # 1 3.08 0 3 mpg value is 18.7 with # 2 3.15 17.02 0 3 mpg value is 18.1 with # 1 2.76

Note this chunk option requires package officedown in a R Markdown context with Word output format.

### minibar

Function compose supports mini barplots insertion. Use function minibar in as_paragraph call:

myft <- flextable( head(iris, n = 10 ))

myft <- compose( myft, j = 1,
value = as_paragraph(
minibar(value = Sepal.Length, max = max(Sepal.Length))
),
part = "body")

autofit(myft)
 Sepal.Length Sepal.Width Petal.Length Petal.Width Species 3.5 1.4 0.2 setosa 3.0 1.4 0.2 setosa 3.2 1.3 0.2 setosa 3.1 1.5 0.2 setosa 3.6 1.4 0.2 setosa 3.9 1.7 0.4 setosa 3.4 1.4 0.3 setosa 3.4 1.5 0.2 setosa 2.9 1.4 0.2 setosa 3.1 1.5 0.1 setosa

Note this chunk option requires package officedown in a R Markdown context with Word output format.

### linerange

Function compose supports mini linerange insertion. Use function linerange in as_paragraph call:

myft <- flextable( head(iris, n = 10 ))

myft <- compose( myft, j = 1,
value = as_paragraph(
linerange(value = Sepal.Length, max = max(Sepal.Length))
),
part = "body")

autofit(myft)
 Sepal.Length Sepal.Width Petal.Length Petal.Width Species 3.5 1.4 0.2 setosa 3.0 1.4 0.2 setosa 3.2 1.3 0.2 setosa 3.1 1.5 0.2 setosa 3.6 1.4 0.2 setosa 3.9 1.7 0.4 setosa 3.4 1.4 0.3 setosa 3.4 1.5 0.2 setosa 2.9 1.4 0.2 setosa 3.1 1.5 0.1 setosa

Note this chunk option requires package officedown in a R Markdown context with Word output format.

### Sugar functions for complex formatting

Functions as_b, as_i, as_sub, as_sup are special functions that can be used together. They set a value as bold, italic, subscripted or superscripted. This is particularly useful when the headers need complex formatting.

data <- structure(list(Species = structure(1:3, .Label = c("setosa",
"versicolor", "virginica"), class = "factor"), col1 = c(5.006,
5.936, 6.588)), class = "data.frame", row.names = c(NA, -3L))

ft <- flextable(data)
ft
 Species col1 setosa 5.006 versicolor 5.936 virginica 6.588
ft <- compose(ft, part = "header", j = "Species",
value = as_paragraph(as_i(as_b("Species"))))
ft <- compose(ft, part = "header", j = "col1",
value = as_paragraph(as_b("µ"), as_sup("blah")))
ft
 Species µblah setosa 5.006 versicolor 5.936 virginica 6.588

## Captions

Captions are supported for HTML and Word output (also from a bookdown project with its specificities taken into account).

Capacities are different from one format to another. For the Word part, we can produce real auto-numbered captions with a bookmark on the automatic number which can then be used as a reference, i.e. for cross-referencing. For the HTML part, you can produce real captions but without the auto-numbering.

Of course, in a bookdown, we benefit from the cross reference capabilities.

The recommended method to set a caption is via the function set_caption. If this function is used, the caption will be defined from here.

Two other methods are available for knitr and are presented below in order of triggering:

1. with knitr’s chunk options:

• tab.cap.style: Word style name to use for table captions.
• tab.cap.pre: Prefix for Word numbering chunk (default to “Table”).
• tab.cap.sep: Suffix for Word numbering chunk (default to “:”).
• tab.cap: Caption label.
• tab.id: Caption Word bookmark (unique identifier).
2. with knitr chunk and bookdown options (if you’re in a bookdown):

• tab.cap.style: Word style name to use for table captions.
• tab.cap.pre: Prefix for Word numbering chunk (default to “Table”).
• tab.cap.sep: Suffix for Word numbering chunk (default to “:”).
• tab.cap: Caption label.
• label: Caption reference unique identifier.

(This css instructions is only there to make the caption styled:)

caption {
color:red;
line-height: 1.5em;
font-size: 10px;
}
ft <- set_caption(ft, caption = "this is a caption")
ft
 Species µblah setosa 5.006 versicolor 5.936 virginica 6.588

You can have a look at R Markdown document illustrating captions for different supported format here:

system.file(package = "flextable", "examples", "rmd", "captions")

Copy one of these files in your working directory and run knitr:

• captions_html_document2.Rmd
• captions_rdocx_document.Rmd
• captions_word_document.Rmd
• captions_word_document2.Rmd

## footnotes

Adding footnotes is possible by using function compose but it requires a two step approach (add the reference symbol and add the corresponding footnote in the footer part).

To make the process simpler, use function footnote that will ease the addition of footnotes.

ft <- flextable(head(iris))
ft <- footnote( ft, i = 1, j = 1:3,
value = as_paragraph(
c("This is footnote one",
"This is footnote two",
"This is footnote three")
),
ref_symbols = c("a", "b", "c"),
ft <- valign(ft, valign = "bottom", part = "header")
autofit(ft)
 Sepal.Lengtha Sepal.Widthb Petal.Lengthc Petal.Width Species 5.1 3.5 1.4 0.2 setosa 4.9 3.0 1.4 0.2 setosa 4.7 3.2 1.3 0.2 setosa 4.6 3.1 1.5 0.2 setosa 5.0 3.6 1.4 0.2 setosa 5.4 3.9 1.7 0.4 setosa aThis is footnote one bThis is footnote two cThis is footnote three

You can also add footnotes inline using the inline argument and specify a seperator string with sep (default “;”)

ft <- flextable(head(iris))
ft <- autofit(ft)
ft <- footnote( ft, i = 1, j = 1:2,
value = as_paragraph(
c("This is footnote one",
"This is footnote two")
),
ref_symbols = c("a", "b"),
ft <- footnote( ft, i = 1, j = 3:4,
value = as_paragraph(
c("This is footnote three",
"This is footnote four")
),
ref_symbols = c( "c","d"),
ft
When designed, flextable was not supposed to support soft return (a new line in a paragraph). As requested by some users, some workarounds have been implemented to let add some \n as soft break in paragraphs.