Format flextable objects

A flextable is made of two parts, an header and a body. To specify which part formatting instructions should affect, use argument part. Possible values are:

Shortcuts functions

There are simple functions to modify formatting properties of flextable objects: bg, bold, border, color, padding, fontsize, italic, align.

myft <- regulartable(head(iris))
tabwid(myft)

bold

myft <- regulartable(head(iris)) %>% 
  # bold header
  bold(part = "header") 
tabwid(myft)

change font color

myft <- myft %>% color(color = "#E4C994")
tabwid(myft)

Italic

myft <- myft %>% 
  italic(i = ~ Sepal.Length > 5, 
         j = ~ Sepal.Length + Sepal.Width, italic = TRUE)
tabwid(myft)

change background color

myft <- myft %>% 
  # light gray as background color for header
  bg(bg = "#E4C994", part = "header") %>% 
  # dark gray as background color for body
  bg(bg = "#333333", part = "body")

tabwid(myft)

Text alignment

myft <- myft %>% align( align = "center", part = "all" )
tabwid(myft)

add padding

myft <- myft %>% padding( padding = 3, part = "all" )
tabwid(myft)

change border

myft <- myft %>% 
  border( border = fp_border(color="white"), part = "all" )
  
tabwid(myft)

Text rotation

Text rotation is possible in flextable objects but will only work with Word and PowerPoint outputs. This is achieved by using function rotate.

Argument rotation is mandatory and expects one of these values:

“lrtb”, left to right top to bottom
“tbrl”, top to bottom right to left
“btlr”, bottom to top left to right

Argument align is used for cell content vertical alignment, it should be one of these values: “top”, “bottom” or “center”.

ft <- regulartable(head(iris)) %>% 
  rotate(rotation = "tbrl", align = "top", part = "header") %>% 
  theme_vanilla() %>% 
  autofit() %>% 
  # as autofit do not handle rotation, you will have
  # to change manually header cells'height.
  height(height = 1, part = "header")

The following example is producing a Word document:

library(officer)
read_docx() %>% 
  body_add_flextable(ft) %>% 
  print(target = "assets/docx/rotate.docx") %>% 
  invisible()

Download file rotate.docx - view with office web viewer

The following example is producing a PowerPoint document:

library(officer)
read_pptx() %>% 
  add_slide(layout = "Title and Content", master = "Office Theme") %>% 
  ph_with_flextable(ft) %>% 
  print(target = "assets/pptx/rotate.pptx") %>% 
  invisible()

Download file rotate.pptx - view with office web viewer

Conditional formatting

Conditional formatting can be made by using the selector arguments.

myft <- myft %>% 
  color(i = ~ Sepal.Length < 5 & Petal.Length > 1.3, 
        j = ~ Petal.Width + Species, 
        color="red") %>% 
  bg(j = 1, bg = "#D3C994", part = "header") %>% 
  italic(i = ~ Sepal.Length > 5) %>% 
  bold( i = 4, j = "Sepal.Length")
tabwid(myft)

i and j arguments can be also standard R vectors:

row_id <- with(head(iris), Sepal.Length < 5 & Petal.Length > 1.3 )
col_id <- c("Petal.Width", "Species")

myft <- color(myft, i = row_id, j = col_id, color="red") 

tabwid(myft)

Function style

The style function lets you style a selection of the flextable with several formatting properties.

It main advantage is to let specify a set of formatting properties for a selection.

Package officer needs to be loaded, it provides the following formatting properties:

for text: fp_text
for paragraphs: fp_par
for cells: fp_cell and fp_border

library(officer)
def_cell <- fp_cell(border = fp_border(color="#00C9C9"))
def_par <- fp_par(text.align = "center")
def_text <- fp_text(color="#999999", italic = TRUE)
def_text_header <- update(color="black", def_text, bold = TRUE)

ft <- regulartable(head(mtcars, n = 10 )) %>% 
  style( pr_c = def_cell, pr_p = def_par, pr_t = def_text, part = "all")  
tabwid(ft)


ft <- ft %>% 
  style( pr_t = def_text_header, part = "header")  
tabwid(ft)

set_formatter function

When working with regulartable, 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.

Note set_formatter only works with regulartable objects, use display for flextable objects.

ft <- regulartable(head(mtcars, n = 10 ), 
                   col_keys = c("gear", "mpg", "qsec")) %>% 
  set_formatter(
    mpg = function(x) sprintf("%.04f", x),
    gear = function(x) sprintf("%.0f gears", x)
  ) %>% 
  theme_booktabs() %>% 
  autofit()
tabwid(ft)

display function

flextable content is defined with display function.

Note display only works with flextable objects, use set_formatter for regulartable objects.

Below the starting point of next illustrations:

myft <- flextable( head(mtcars), 
  col_keys = c("am", "separator", "gear", "mpg", "drat", "qsec" )) %>% 
  bold(part = "header") %>% 
  border(border = fp_border( width = 0), 
         border.top = fp_border(), border.bottom = fp_border(), 
         part = "all") %>% 
  align(align = "right", part = "all" ) %>%
  border(j = ~ separator, border = fp_border(width=0), part = "all") %>% 
  width(j = ~ separator, width = .1)

tabwid(myft)

The function requires argument pattern which is a string template inspired by mustaches. The string will be expanded with tags using values provided in formatters argument; tags can eventually be formatted with fprops argument.

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 <- myft %>%
  display( col_key = "mpg", pattern = "{{mpg}}", 
           formatters = list(mpg ~ sprintf("%.01f", mpg) ), 
              fprops = list(mpg = fp_text(color = "red", italic = TRUE) )
  )

tabwid(myft)

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

myft <- myft %>%
  display( i = ~ drat > 3.6, 
           col_key = "mpg", pattern = "{{mpg}} with {{carb}}", 
           formatters = list(mpg ~ sprintf("%.01f", mpg), 
                             carb ~ sprintf("# %.0f carb.", carb) ), 
              fprops = list(mpg = fp_text(color = "#CC55CC", bold = TRUE) )
  ) %>% autofit()

tabwid(myft)

Or to define specific title headers:

myft <- myft %>%
  display( col_key = "mpg", pattern = "{{mpg}} {{my_message}}", part = "header",
           formatters = list(mpg ~ "Miles/(US) gallon", 
                             my_message ~ sprintf("* with num of carb.") ), 
              fprops = list(my_message = fp_text(color = "gray", vertical.align = "superscript")
                            )
  ) %>% autofit()

tabwid(myft)

Images

Function display supports images insertion. Use function as_image within formatters argument.

img.file <- file.path( Sys.getenv("R_HOME"), "doc", "html", "logo.jpg" )

myft <- myft %>%
  display( i = ~ qsec > 18, col_key = "qsec", 
           pattern = "blah blah {{r_logo}} {{qsec}}",
           formatters = list(
             r_logo ~ as_image(qsec, src = img.file, width = .20, height = .15), 
             qsec ~ sprintf("qsec: %.1f", qsec) ), 
           fprops = list(qsec = fp_text(color = "orange", vertical.align = "superscript"))
           ) %>% 
  autofit()

tabwid(myft)