blob: a98ae10c07cfab41cae061d9c8f744042dc9c442 [file] [log] [blame]
Hao Zhu6a076462017-03-01 12:59:01 -05001---
2title: "Create Awesome HTML Table with knitr::kable and kableExtra"
3author: "Hao Zhu"
4date: "`r Sys.Date()`"
5output:
6 html_document:
Hao Zhufd00fec2017-03-01 19:23:08 -05007 theme: simplex
Hao Zhu6a076462017-03-01 12:59:01 -05008 toc: true
9 toc_depth: 2
10 toc_float: true
11vignette: >
12 %\VignetteIndexEntry{Create Awesome HTML Table with knitr::kable and kableExtra}
13 %\VignetteEngine{knitr::rmarkdown}
14 %\VignetteEncoding{UTF-8}
15---
16
Hao Zhu3e21ff92020-08-20 08:24:07 -040017<script>
18$(document).ready(function(){
19 $('[data-toggle="popover"]').popover();
20});
21</script>
22
Hao Zhudda2f722018-05-21 00:38:11 -040023<img src="kableExtra_sm.png" align="right" alt="logo" width="80" height = "93" style = "border: none; float: right;">
24
Hao Zhu5fe235c2020-08-26 00:26:49 -040025> Please see the package [documentation site](https://haozhu233.github.io/kableExtra/) for how to use this package in LaTeX.
Hao Zhu6ce29212017-05-22 16:29:56 -040026
Hao Zhu6a076462017-03-01 12:59:01 -050027# Overview
28The goal of `kableExtra` is to help you build common complex tables and manipulate table styles. It imports the pipe `%>%` symbol from `magrittr` and verbalize all the functions, so basically you can add "layers" to a kable output in a way that is similar with `ggplot2` and `plotly`.
29
Hao Zhu3e21ff92020-08-20 08:24:07 -040030For users who are not very familiar with the pipe operator `%>%` in R, it is the R version of the [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface). The ides is to pass the result along the chain for a more literal coding experience. Basically when we say `A %>% B`, technically it means sending the results of A to B as B's first argument.
31
Hao Zhu53e240f2017-09-04 20:04:29 -040032To learn how to generate complex tables in LaTeX, please visit [http://haozhu233.github.io/kableExtra/awesome_table_in_pdf.pdf](http://haozhu233.github.io/kableExtra/awesome_table_in_pdf.pdf)
33
Hao Zhu6107f372018-05-21 00:23:26 -040034There is also a Chinese version of this vignette. You can find it [here](http://haozhu233.github.io/kableExtra/awesome_table_in_html_cn.html)
35
Hao Zhu6a076462017-03-01 12:59:01 -050036# Installation
Hao Zhu6a076462017-03-01 12:59:01 -050037```r
Hao Zhu74eb6ad2017-03-04 09:32:37 -050038install.packages("kableExtra")
39
Hao Zhu6a076462017-03-01 12:59:01 -050040# For dev version
Hao Zhuf9aa4c42017-05-22 15:53:35 -040041# install.packages("devtools")
Hao Zhu6a076462017-03-01 12:59:01 -050042devtools::install_github("haozhu233/kableExtra")
43```
44# Getting Started
45Here we are using the first few columns and rows from dataset `mtcars`
46```{r}
Hao Zhu6a076462017-03-01 12:59:01 -050047library(kableExtra)
48dt <- mtcars[1:5, 1:6]
49```
50
Hao Zhu3e21ff92020-08-20 08:24:07 -040051> **Key Update:** In the latest version of this package (1.2+), we provide a wrapper funciton `kbl` to the original `kable` function with detailed documentation of all the hidden html/latex options. It also does auto-formatting check in every function call instead of relying on the global environement variable. As a result, it also solves an issue for multi-format R Markdown documents. I encourage you start to use the new `kbl` function for all its convenience but the support for the original `kable` function is still there. In this doc, we will use `kbl` instead of `kable`.
Hao Zhu6107f372018-05-21 00:23:26 -040052
Hao Zhu6107f372018-05-21 00:23:26 -040053
Hao Zhu3e21ff92020-08-20 08:24:07 -040054**This paragraph is a little outdated. It's here only for education purpose because it's helpful to understand how `kable` works under the hood**. When you are using `kable()`, if you don't specify `format`, by default it will generate a markdown table and let pandoc handle the conversion from markdown to HTML/PDF. This is the most favorable approach to render most simple tables as it is format independent. If you switch from HTML to pdf, you basically don't need to change anything in your code. However, markdown doesn't support complex table. For example, if you want to have a double-row header table, markdown just cannot provide you the functionality you need. As a result, when you have such a need, you should **define `format` in `kable()`** as either "html" or "latex". *You can also define a global option at the beginning using `options(knitr.table.format = "html")` so you don't repeat the step everytime.* **Starting from `kableExtra` 0.9.0**, when you load this package (`library(kableExtra)`), it will automatically set up the global option 'knitr.table.format' based on your current environment. Unless you are rendering a PDF, `kableExtra` will try to render a HTML table for you. **You no longer need to manually set either the global option or the `format` option in each `kable()` function**. I'm still including the explanation above here in this vignette so you can understand what is going on behind the scene. Note that this is only an global option. You can manually set any format in `kable()` whenever you want. I just hope you can enjoy a peace of mind in most of your time. You can disable this behavior by setting `options(kableExtra.auto_format = FALSE)` before you load `kableExtra`.
Hao Zhu6a076462017-03-01 12:59:01 -050055
56```{r}
Hao Zhu6107f372018-05-21 00:23:26 -040057# If you are using kableExtra < 0.9.0, you are recommended to set a global option first.
58# options(knitr.table.format = "html")
Hao Zhu6a076462017-03-01 12:59:01 -050059## If you don't define format here, you'll need put `format = "html"` in every kable function.
60```
61
Hao Zhu53e240f2017-09-04 20:04:29 -040062## Basic HTML table
Hao Zhu6a076462017-03-01 12:59:01 -050063Basic HTML output of `kable` looks very crude. To the end, it's just a plain HTML table without any love from css.
64```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -040065kbl(dt)
Hao Zhu6a076462017-03-01 12:59:01 -050066```
67
Hao Zhu53e240f2017-09-04 20:04:29 -040068## Bootstrap theme
Hao Zhu6a076462017-03-01 12:59:01 -050069When used on a HTML table, `kable_styling()` will automatically apply twitter bootstrap theme to the table. Now it should looks the same as the original pandoc output (the one when you don't specify `format` in `kable()`) but this time, you are controlling it.
70```{r}
Hao Zhu4840bc92017-09-15 15:55:05 -040071dt %>%
Hao Zhu3e21ff92020-08-20 08:24:07 -040072 kbl() %>%
Hao Zhu6a076462017-03-01 12:59:01 -050073 kable_styling()
74```
75
Hao Zhu3e21ff92020-08-20 08:24:07 -040076## Alternative themes
77`kableExtra` also offers a few in-house alternative HTML table themes other than the default bootstrap theme. Right now there are 6 of them: `kable_paper`, `kable_classic`, `kable_classic_2`, `kable_minimal`, `kable_material` and `kable_material_dark`. These functions are alternatives to `kable_styling`, which means that you can specify any additional formatting options in `kable_styling` in these functions too. The only difference is that `bootstrap_options` (as discussed in the next section) is replaced with `lightable_options` at the same location with only two choices `striped` and `hover` available.
78
79```{r}
80dt %>%
81 kbl() %>%
Hao Zhu9399dcc2020-08-26 17:27:38 -040082 kable_paper("hover", full_width = F)
Hao Zhu3e21ff92020-08-20 08:24:07 -040083```
84
85```{r}
86dt %>%
87 kbl(caption = "Recreating booktabs style table") %>%
88 kable_classic(full_width = F, html_font = "Cambria")
89```
90
91```{r}
92dt %>%
93 kbl() %>%
Hao Zhu9399dcc2020-08-26 17:27:38 -040094 kable_classic_2(full_width = F)
Hao Zhu3e21ff92020-08-20 08:24:07 -040095```
96
97```{r}
98dt %>%
99 kbl() %>%
100 kable_minimal()
101```
102
103```{r}
104dt %>%
105 kbl() %>%
106 kable_material(c("striped", "hover"))
107```
108
109```{r}
110dt %>%
111 kbl() %>%
112 kable_material_dark()
113```
114
115
116
Hao Zhu6a076462017-03-01 12:59:01 -0500117# Table Styles
Hao Zhu53e240f2017-09-04 20:04:29 -0400118`kable_styling` offers a few other ways to customize the look of a HTML table.
Hao Zhu6a076462017-03-01 12:59:01 -0500119
Hao Zhu53e240f2017-09-04 20:04:29 -0400120## Bootstrap table classes
Hao Zhu5fe235c2020-08-26 00:26:49 -0400121If you are familiar with twitter bootstrap, you probably have already known its predefined classes, including `striped`, `bordered`, `hover`, `condensed` and `responsive`. If you are not familiar, no worries, you can take a look at their [documentation site](https://getbootstrap.com/css/) to get a sense of how they look like. All of these options are available here.
Hao Zhu6a076462017-03-01 12:59:01 -0500122
123For example, to add striped lines (alternative row colors) to your table and you want to highlight the hovered row, you can simply type:
124```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400125kbl(dt) %>%
Hao Zhu6a076462017-03-01 12:59:01 -0500126 kable_styling(bootstrap_options = c("striped", "hover"))
127```
128
129The option `condensed` can also be handy in many cases when you don't want your table to be too large. It has slightly shorter row height.
130```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400131kbl(dt) %>%
Hao Zhu6a076462017-03-01 12:59:01 -0500132 kable_styling(bootstrap_options = c("striped", "hover", "condensed"))
133```
134
135Tables with option `responsive` looks the same with others on a large screen. However, on a small screen like phone, they are horizontally scrollable. Please resize your window to see the result.
136```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400137kbl(dt) %>%
Hao Zhu6a076462017-03-01 12:59:01 -0500138 kable_styling(bootstrap_options = c("striped", "hover", "condensed", "responsive"))
139```
140
Hao Zhu53e240f2017-09-04 20:04:29 -0400141## Full width?
Hao Zhuf9aa4c42017-05-22 15:53:35 -0400142By default, a bootstrap table takes 100% of the width. It is supposed to use together with its grid system to scale the table properly. However, when you are writing a rmarkdown document, you probably don't want to write your own css/or grid. For some small tables with only few columns, a page wide table looks awful. To make it easier, you can specify whether you want the table to have `full_width` or not in `kable_styling`. By default, `full_width` is set to be `TRUE` for HTML tables (note that for LaTeX, the default is `FALSE` since I don't want to change the "common" looks unless you specified it.)
Hao Zhu6a076462017-03-01 12:59:01 -0500143```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400144kbl(dt) %>%
145 kable_paper(bootstrap_options = "striped", full_width = F)
Hao Zhu6a076462017-03-01 12:59:01 -0500146```
147
148## Position
149Table Position only matters when the table doesn't have `full_width`. You can choose to align the table to `center`, `left` or `right` side of the page
150```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400151kbl(dt) %>%
Hao Zhu6a076462017-03-01 12:59:01 -0500152 kable_styling(bootstrap_options = "striped", full_width = F, position = "left")
153```
154
155Becides these three common options, you can also wrap text around the table using the `float-left` or `float-right` options.
156```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400157kbl(dt) %>%
Hao Zhu6a076462017-03-01 12:59:01 -0500158 kable_styling(bootstrap_options = "striped", full_width = F, position = "float_right")
159```
160Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras sit amet mauris in ex ultricies elementum vel rutrum dolor. Phasellus tempor convallis dui, in hendrerit mauris placerat scelerisque. Maecenas a accumsan enim, a maximus velit. Pellentesque in risus eget est faucibus convallis nec at nulla. Phasellus nec lacinia justo. Morbi fermentum, orci id varius accumsan, nibh neque porttitor ipsum, consectetur luctus risus arcu ac ex. Aenean a luctus augue. Suspendisse et auctor nisl. Suspendisse cursus ultrices quam non vulputate. Phasellus et pharetra neque, vel feugiat erat. Sed feugiat elit at mauris commodo consequat. Sed congue lectus id mattis hendrerit. Mauris turpis nisl, congue eget velit sed, imperdiet convallis magna. Nam accumsan urna risus, non feugiat odio vehicula eget.
161
Hao Zhu53e240f2017-09-04 20:04:29 -0400162## Font size
Hao Zhu6a076462017-03-01 12:59:01 -0500163If one of your tables is huge and you want to use a smaller font size for that specific table, you can use the `font_size` option.
164```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400165kbl(dt) %>%
Hao Zhu6a076462017-03-01 12:59:01 -0500166 kable_styling(bootstrap_options = "striped", font_size = 7)
167```
168
Hao Zhu72917f92019-03-15 18:41:42 -0400169## Fixed Table Header Row
170If you happened to have a very long table, you may consider to use this `fixed_header` option to fix the header row on top as your readers scroll. By default, the background is set to white. If you need a different color, you can set `fixed_header = list(enabled = T, background = "red")`.
171
172```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400173kbl(mtcars[1:10, 1:5]) %>%
Hao Zhu72917f92019-03-15 18:41:42 -0400174 kable_styling(fixed_thead = T)
175```
176
Hao Zhu53e240f2017-09-04 20:04:29 -0400177# Column / Row Specification
178## Column spec
Hao Zhu4840bc92017-09-15 15:55:05 -0400179When you have a table with lots of explanatory texts, you may want to specified the column width for different column, since the auto adjust in HTML may not work in its best way while basic LaTeX table is really bad at handling text wrapping. Also, sometimes, you may want to highlight a column (e.g. a "Total" column) by making it bold. In these scenario, you can use `column_spec()`. You can find an example below.
Hao Zhu53e240f2017-09-04 20:04:29 -0400180
181Warning: If you have a super long table, you should be cautious when you use `column_spec` as the xml node modification takes time.
182
183```{r}
184text_tbl <- data.frame(
185 Items = c("Item 1", "Item 2", "Item 3"),
186 Features = c(
187 "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin vehicula tempor ex. Morbi malesuada sagittis turpis, at venenatis nisl luctus a. ",
188 "In eu urna at magna luctus rhoncus quis in nisl. Fusce in velit varius, posuere risus et, cursus augue. Duis eleifend aliquam ante, a aliquet ex tincidunt in. ",
189 "Vivamus venenatis egestas eros ut tempus. Vivamus id est nisi. Aliquam molestie erat et sollicitudin venenatis. In ac lacus at velit scelerisque mattis. "
190 )
191)
192
Hao Zhu3e21ff92020-08-20 08:24:07 -0400193kbl(text_tbl) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400194 kable_paper(full_width = F) %>%
Hao Zhufb0a6d42017-09-07 17:21:02 -0400195 column_spec(1, bold = T, border_right = T) %>%
196 column_spec(2, width = "30em", background = "yellow")
Hao Zhu53e240f2017-09-04 20:04:29 -0400197```
198
Hao Zhu3e21ff92020-08-20 08:24:07 -0400199> **Key Update**: I understand the need of doing conditional formatting and the previous solution `cell_spec` is relatively hard to use. Therefore in kableExtra 1.2, I improved the functionality of `column_spec` so it can take vectorized input for most of its arguments (except `width`, `border_left` and `border_right`). It is really easy right now to format a column based on other values.
Hao Zhu53e240f2017-09-04 20:04:29 -0400200
201```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400202mtcars[1:8, 1:8] %>%
203 kbl() %>%
204 kable_paper(full_width = F) %>%
205 column_spec(2, color = spec_color(mtcars$mpg[1:8]),
Hao Zhu9399dcc2020-08-26 17:27:38 -0400206 link = "https://haozhu233.github.io/kableExtra/") %>%
Hao Zhu3e21ff92020-08-20 08:24:07 -0400207 column_spec(6, color = "white",
208 background = spec_color(mtcars$drat[1:8], end = 0.7),
209 popover = paste("am:", mtcars$am[1:8]))
210```
211
212You can still use the `spec_***` helper functions to help you define color. See the documentation [below](#visualize-data-with-viridis-color).
213
Hao Zhu5fe235c2020-08-26 00:26:49 -0400214## Insert Images into Columns
215Technically, we are still talking about `column_spec` here. However, since this topic itself contains its own subtopics, we split it out as a separate section. Since `kableExtra` 1.2, we introduced the feature of adding images to columns of tables. Here is a quick example.
216
217```{r}
218tbl_img <- data.frame(
219 name = c("kableExtra 1", "kableExtra 2"),
220 logo = ""
221)
222tbl_img %>%
223 kbl(booktabs = T) %>%
224 kable_paper(full_width = F) %>%
225 column_spec(2, image = "kableExtra_sm.png")
226```
227
228If you need to specify the size of the images, you need to do it through `spec_image`.
229
230```{r}
231tbl_img %>%
232 kbl(booktabs = T) %>%
233 kable_paper(full_width = F) %>%
234 column_spec(2, image = spec_image(
235 c("kableExtra_sm.png", "kableExtra_sm.png"), 50, 50))
236```
237
Bill Evans548d7152020-09-13 21:44:24 -0700238`kableExtra` also provides a few inline plotting tools. Right now, there are `spec_hist`, `spec_boxplot`, and `spec_plot`. One key feature is that by default, the limits of every subplots are fixed so you can compare across rows. Note that in html, you can also use package `sparkline` to create some jquery based interactive sparklines. Check out the end of this guide for details.
Hao Zhu5fe235c2020-08-26 00:26:49 -0400239
240```{r}
241mpg_list <- split(mtcars$mpg, mtcars$cyl)
Bill Evanse4e281b2020-09-13 21:57:47 -0700242disp_list <- split(mtcars$disp, mtcars$cyl)
243inline_plot <- data.frame(cyl = c(4, 6, 8), mpg_box = "", mpg_hist = "",
244 mpg_line1 = "", mpg_line2 = "",
245 mpg_points1 = "", mpg_points2 = "", mpg_poly = "")
246inline_plot %>%
247 kbl(booktabs = TRUE) %>%
248 kable_paper(full_width = FALSE) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400249 column_spec(2, image = spec_boxplot(mpg_list)) %>%
Bill Evanscebc9712020-08-30 19:55:24 -0700250 column_spec(3, image = spec_hist(mpg_list)) %>%
Bill Evanse4e281b2020-09-13 21:57:47 -0700251 column_spec(4, image = spec_plot(mpg_list, same_lim = TRUE)) %>%
252 column_spec(5, image = spec_plot(mpg_list, same_lim = FALSE)) %>%
253 column_spec(6, image = spec_plot(mpg_list, type = "p")) %>%
254 column_spec(7, image = spec_plot(mpg_list, disp_list, type = "p")) %>%
255 column_spec(8, image = spec_plot(mpg_list, polymin = 5))
Hao Zhu5fe235c2020-08-26 00:26:49 -0400256```
257
Hao Zhu3e21ff92020-08-20 08:24:07 -0400258## Row spec
259Similar with `column_spec`, you can define specifications for rows. Currently, you can either bold or italicize an entire row. Note that, similar with other row-related functions in `kableExtra`, for the position of the target row, you don't need to count in header rows or the group labeling rows.
260
261```{r}
262kbl(dt) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400263 kable_paper("striped", full_width = F) %>%
Hao Zhu4840bc92017-09-15 15:55:05 -0400264 column_spec(5:7, bold = T) %>%
265 row_spec(3:5, bold = T, color = "white", background = "#D7261E")
Hao Zhu53e240f2017-09-04 20:04:29 -0400266```
267
Hao Zhu6290fdd2017-10-24 00:10:32 -0400268
269
270## Header Rows
271One special case of `row_spec` is that you can specify the format of the header row via `row_spec(row = 0, ...)`.
272```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400273kbl(dt) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400274 kable_paper("striped", full_width = F) %>%
Hao Zhu6290fdd2017-10-24 00:10:32 -0400275 row_spec(0, angle = -45)
276```
277
278# Cell/Text Specification
Salim Bf2652cd2019-05-17 02:21:14 +0000279
Hao Zhu3e21ff92020-08-20 08:24:07 -0400280>**Key Update: As said before, if you are using kableExtra 1.2+, you are now recommended to used `column_spec` to do conditional formatting**.
281
282Function `cell_spec` is introduced in version 0.6.0 of `kableExtra`. Unlike `column_spec` and `row_spec`, **this function is designed to be used before the data.frame gets into the `kable` function**. Comparing with figuring out a list of 2 dimentional index for targeted cells, this design is way easier to learn and use and it fits perfectly well with `dplyr`'s `mutate` and `summarize` functions. With this design, there are two things to be noted:
Hao Zhu6290fdd2017-10-24 00:10:32 -0400283* Since `cell_spec` generates raw `HTML` or `LaTeX` code, make sure you remember to put `escape = FALSE` in `kable`. At the same time, you have to escape special symbols including `%` manually by yourself
284* `cell_spec` needs a way to know whether you want `html` or `latex`. You can specify it locally in function or globally via the `options(knitr.table.format = "latex")` method as suggested at the beginning. If you don't provide anything, this function will output as HTML by default.
285
286Currently, `cell_spec` supports features including bold, italic, monospace, text color, background color, align, font size & rotation angle. More features may be added in the future. Please see function documentations as reference.
287
288## Conditional logic
Hao Zhu3e21ff92020-08-20 08:24:07 -0400289>**Key Update: Again, as said before, if you are using kableExtra 1.2+, you are now recommended to used `column_spec` to do conditional formatting**.
290
Hao Zhu6290fdd2017-10-24 00:10:32 -0400291It is very easy to use `cell_spec` with conditional logic. Here is an example.
292```{r, message=FALSE, warning=FALSE}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400293cs_dt <- mtcars[1:10, 1:2]
294cs_dt$car = row.names(cs_dt)
295row.names(cs_dt) <- NULL
296cs_dt$mpg = cell_spec(cs_dt$mpg, color = ifelse(cs_dt$mpg > 20, "red", "blue"))
297cs_dt$cyl = cell_spec(
298 cs_dt$cyl, color = "white", align = "c", angle = 45,
299 background = factor(cs_dt$cyl, c(4, 6, 8), c("#666666", "#999999", "#BBBBBB")))
300cs_dt <- cs_dt[c("car", "mpg", "cyl")]
301
302kbl(cs_dt, escape = F) %>%
303 kable_paper("striped", full_width = F)
304
305# You can also do this with dplyr and use one pipe from top to bottom
306# library(dplyr)
307# mtcars[1:10, 1:2] %>%
308# mutate(
309# car = row.names(.),
310# mpg = cell_spec(mpg, "html", color = ifelse(mpg > 20, "red", "blue")),
311# cyl = cell_spec(cyl, "html", color = "white", align = "c", angle = 45,
312# background = factor(cyl, c(4, 6, 8),
313# c("#666666", "#999999", "#BBBBBB")))
314# ) %>%
315# select(car, mpg, cyl) %>%
316# kbl(format = "html", escape = F) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400317# kable_paper("striped", full_width = F)
Hao Zhu6290fdd2017-10-24 00:10:32 -0400318```
319
320## Visualize data with Viridis Color
Hao Zhu3e21ff92020-08-20 08:24:07 -0400321This package also comes with a few helper functions, including `spec_color`, `spec_font_size` & `spec_angle`. These functions can rescale continuous variables to certain scales. For example, function `spec_color` would map a continuous variable to any [viridis color palettes](https://CRAN.R-project.org/package=viridisLite). It offers a very visually impressive representation in a tabular format.
Hao Zhu6290fdd2017-10-24 00:10:32 -0400322
323```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400324vs_dt <- iris[1:10, ]
325vs_dt[1:4] <- lapply(vs_dt[1:4], function(x) {
Hao Zhu6107f372018-05-21 00:23:26 -0400326 cell_spec(x, bold = T,
Hao Zhu5e4dd502018-04-05 12:01:58 -0400327 color = spec_color(x, end = 0.9),
Hao Zhu6290fdd2017-10-24 00:10:32 -0400328 font_size = spec_font_size(x))
Hao Zhu3e21ff92020-08-20 08:24:07 -0400329})
330vs_dt[5] <- cell_spec(vs_dt[[5]], color = "white", bold = T,
331 background = spec_color(1:10, end = 0.9, option = "A", direction = -1))
332kbl(vs_dt, escape = F, align = "c") %>%
333 kable_classic("striped", full_width = F)
334# Or dplyr ver
335# iris[1:10, ] %>%
336# mutate_if(is.numeric, function(x) {
337# cell_spec(x, bold = T,
338# color = spec_color(x, end = 0.9),
339# font_size = spec_font_size(x))
340# }) %>%
341# mutate(Species = cell_spec(
342# Species, color = "white", bold = T,
343# background = spec_color(1:10, end = 0.9, option = "A", direction = -1)
344# )) %>%
345# kable(escape = F, align = "c") %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400346# kable_paper(c("striped", "condensed"), full_width = F)
Hao Zhu6290fdd2017-10-24 00:10:32 -0400347```
348
Hao Zhu6290fdd2017-10-24 00:10:32 -0400349## Text Specification
350If you check the results of `cell_spec`, you will find that this function does nothing more than wrapping the text with appropriate HTML/LaTeX formatting syntax. The result of this function is just a vector of character strings. As a result, when you are writing a `rmarkdown` document or write some text in shiny apps, if you need extra markups other than **bold** or *italic*, you may use this function to `r text_spec("color", color = "red")`, `r text_spec("change font size ", font_size = 16)` or `r text_spec("rotate", angle = 30)` your text.
351
352An aliased function `text_spec` is also provided for a more literal writing experience. In HTML, there is no difference between these two functions.
353
354```{r}
355sometext <- strsplit(paste0(
356 "You can even try to make some crazy things like this paragraph. ",
Hao Zhu6a1cbb52017-10-24 15:54:50 -0400357 "It may seem like a useless feature right now but it's so cool ",
358 "and nobody can resist. ;)"
Hao Zhu6290fdd2017-10-24 00:10:32 -0400359), " ")[[1]]
360text_formatted <- paste(
Hao Zhu6107f372018-05-21 00:23:26 -0400361 text_spec(sometext, color = spec_color(1:length(sometext), end = 0.9),
Hao Zhu6290fdd2017-10-24 00:10:32 -0400362 font_size = spec_font_size(1:length(sometext), begin = 5, end = 20)),
363 collapse = " ")
364
365# To display the text, type `r text_formatted` outside of the chunk
366```
367`r text_formatted`
368
369## Tooltip
370It's very easy to add a tooltip to text via `cell_spec`. For example, `text_spec("tooltip", color = "red", tooltip = "Hello World")` will give you something like `r text_spec("Hover over me", color = "red", tooltip = "Hello World")` (you need to wait for a few seconds before your browser renders it).
371
372Note that the original browser-based tooltip is slow. If you want to have a faster response, you may want to initialize bootstrap's tooltip by putting the following HTML code on the page.
373```
374<script>
375$(document).ready(function(){
376 $('[data-toggle="tooltip"]').tooltip();
377});
378</script>
379```
380
381In a rmarkdown document, you can just drop it outside of any R chunks. Unfortunately however, for rmarkdown pages with a **floating TOC** (like this page), you can't use bootstrap tooltips because there is a conflict in namespace between Bootstrap and JQueryUI (tocify.js). As a result, I can't provide a live demo here. If you want to have a tooltip together with a floating TOC, you should use `popover` which has a very similar effect.
382
383
384
385## Popover Message
386The popover message looks very similar with tooltip but it can hold more contents. Unlike tooltip which can minimally work without you manually enable that module, you **have to** enable the `popover` module to get it work. The upper side is that there is no conflict between Bootstrap & JQueryUI this time, you can use it without any concern.
387
388```
389<script>
390$(document).ready(function(){
391 $('[data-toggle="popover"]').popover();
392});
393</script>
394```
395
Hao Zhu6290fdd2017-10-24 00:10:32 -0400396```{r}
397popover_dt <- data.frame(
398 position = c("top", "bottom", "right", "left"),
399 stringsAsFactors = FALSE
400)
401popover_dt$`Hover over these items` <- cell_spec(
402 paste("Message on", popover_dt$position), # Cell texts
403 popover = spec_popover(
404 content = popover_dt$position,
405 title = NULL, # title will add a Title Panel on top
406 position = popover_dt$position
407 ))
Hao Zhu3e21ff92020-08-20 08:24:07 -0400408kbl(popover_dt, escape = FALSE) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400409 kable_paper("striped", full_width = FALSE)
Hao Zhu6290fdd2017-10-24 00:10:32 -0400410```
411
412## Links
Hao Zhu5fe235c2020-08-26 00:26:49 -0400413You can add links to text via `text_spec("kableExtra", link = "https://haozhu233.github.io/kableExtra/")`: `r text_spec("kableExtra", link = "https://haozhu233.github.io/kableExtra/")`. If you want your hover message to be more obvious, it might be a good idea to put a `#` (go back to the top of the page) or `javascript:void(0)` (literally do nothing) in the `link` option.
Hao Zhu9567e632017-10-24 09:51:09 -0400414`text_spec("Hover on me", link = "javascript:void(0)", popover = "Hello")`:
415`r text_spec("Hover on me", link = "javascript:void(0)", popover = "Hello")`
Hao Zhu6290fdd2017-10-24 00:10:32 -0400416
Hao Zhu8b32b192017-10-24 14:51:48 -0400417## Integration with `formattable`
418You can combine the good parts from `kableExtra` & `formattable` together into one piece. Read more at http://haozhu233.github.io/kableExtra/use_kableExtra_with_formattable.html
419```{r, message = FALSE, warning=FALSE}
420library(formattable)
Hao Zhu3e21ff92020-08-20 08:24:07 -0400421ft_dt <- mtcars[1:5, 1:4]
422ft_dt$car <- row.names(ft_dt)
423row.names(ft_dt) <- NULL
424ft_dt$mpg <- color_tile("white", "orange")(ft_dt$mpg)
425ft_dt$cyl <- cell_spec(ft_dt$cyl, angle = (1:5)*60,
426 background = "red", color = "white", align = "center")
427ft_dt$disp <- ifelse(
428 ft_dt$disp > 200,
429 cell_spec(ft_dt$disp, color = "red", bold = T),
430 cell_spec(ft_dt$disp, color = "green", italic = T)
431)
432ft_dt$hp <- color_bar("lightgreen")(ft_dt$hp)
433ft_dt <- ft_dt[c("car", "mpg", "cyl", "disp", "hp")]
434
435kbl(ft_dt, escape = F) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400436 kable_paper("hover", full_width = F) %>%
Hao Zhu8b32b192017-10-24 14:51:48 -0400437 column_spec(5, width = "3cm") %>%
438 add_header_above(c(" ", "Hello" = 2, "World" = 2))
439```
440
Hao Zhu53e240f2017-09-04 20:04:29 -0400441# Grouped Columns / Rows
442## Add header rows to group columns
Hao Zhu6a076462017-03-01 12:59:01 -0500443Tables with multi-row headers can be very useful to demonstrate grouped data. To do that, you can pipe your kable object into `add_header_above()`. The header variable is supposed to be a named character with the names as new column names and values as column span. For your convenience, if column span equals to 1, you can ignore the `=1` part so the function below can be written as `add_header_above(c(" ", "Group 1" = 2, "Group 2" = 2, "Group 3" = 2)).
444```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400445kbl(dt) %>%
446 kable_classic() %>%
Hao Zhu6a076462017-03-01 12:59:01 -0500447 add_header_above(c(" " = 1, "Group 1" = 2, "Group 2" = 2, "Group 3" = 2))
448```
449
Hao Zhu4c4bf8d2017-07-03 19:38:11 -0400450In fact, if you want to add another row of header on top, please feel free to do so.
Hao Zhu6a076462017-03-01 12:59:01 -0500451```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400452kbl(dt) %>%
453 kable_paper() %>%
Hao Zhu6a076462017-03-01 12:59:01 -0500454 add_header_above(c(" ", "Group 1" = 2, "Group 2" = 2, "Group 3" = 2)) %>%
455 add_header_above(c(" ", "Group 4" = 4, "Group 5" = 2)) %>%
456 add_header_above(c(" ", "Group 6" = 6))
457```
458
Hao Zhu53e240f2017-09-04 20:04:29 -0400459## Group rows via labeling
Hao Zhu72917f92019-03-15 18:41:42 -0400460Sometimes we want a few rows of the table being grouped together. They might be items under the same topic (e.g., animals in one species) or just different data groups for a categorical variable (e.g., age < 40, age > 40). With the function `group_rows()`/`pack_rows()` in `kableExtra`, this kind of task can be completed in one line. Please see the example below. Note that when you count for the start/end rows of the group, you don't need to count for the header rows nor other group label rows. You only need to think about the row numbers in the "original R dataframe".
Hao Zhu53e240f2017-09-04 20:04:29 -0400461```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400462kbl(mtcars[1:10, 1:6], caption = "Group Rows") %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400463 kable_paper("striped", full_width = F) %>%
Hao Zhu72917f92019-03-15 18:41:42 -0400464 pack_rows("Group 1", 4, 7) %>%
465 pack_rows("Group 2", 8, 10)
Hao Zhu53e240f2017-09-04 20:04:29 -0400466```
467
Hao Zhu72917f92019-03-15 18:41:42 -0400468Another way to use `pack_rows` is to provide an grouping index, similar with `add_header_above()`. This feature is only available in kableExtra > 0.5.2.
Hao Zhu4840bc92017-09-15 15:55:05 -0400469```{r, eval = F}
470# Not evaluated. This example generates the same table as above.
Hao Zhu3e21ff92020-08-20 08:24:07 -0400471kbl(mtcars[1:10, 1:6], caption = "Group Rows") %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400472 kable_paper("striped", full_width = F) %>%
Hao Zhu72917f92019-03-15 18:41:42 -0400473 pack_rows(index = c(" " = 3, "Group 1" = 4, "Group 2" = 3))
Hao Zhu4840bc92017-09-15 15:55:05 -0400474```
475
Hao Zhu53e240f2017-09-04 20:04:29 -0400476For advanced users, you can even define your own css for the group labeling.
477```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400478kbl(dt) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400479 kable_paper("striped", full_width = F) %>%
Hao Zhu72917f92019-03-15 18:41:42 -0400480 pack_rows("Group 1", 3, 5, label_row_css = "background-color: #666; color: #fff;")
481```
482
483`r text_spec("Important Note!", bold = T, color = "#D7261E")`
484
485Note that `dplyr` 0.8.0+ introduced a `group_rows` function as well for a trivial feature. Therefore, I'm create this `pack_rows` function as an alias to the original `group_rows`. In the future, **I recommend all kableExtra users to use `pack_rows` instead of `group_rows` to get rid of the NAMESPACE conflict.**
486
487Alternatively, for pre-existing codes, you have two ways to solve this. You can either load `kableExtra` after `dplyr` or `tidyverse`, or to use the `conflicted` package. Here is an example.
488
489```{r, eval=F}
490# Method 1
491pack_rows() # instead of group_rows()
492
493# Method 2
494library(dplyr)
495library(kableExtra)
496
497# Method 3
498conflicted::conflict_prefer("group_rows", "kableExtra", "dplyr")
Hao Zhu53e240f2017-09-04 20:04:29 -0400499```
500
501## Row indentation
Hao Zhu72917f92019-03-15 18:41:42 -0400502Unlike `pack_rows()`, which will insert a labeling row, sometimes we want to list a few sub groups under a total one. In that case, `add_indent()` is probably more apporiate.
Hao Zhu53e240f2017-09-04 20:04:29 -0400503For advanced users, you can even define your own css for the group labeling.
504```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400505kbl(dt) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400506 kable_paper("striped", full_width = F) %>%
Hao Zhu53e240f2017-09-04 20:04:29 -0400507 add_indent(c(1, 3, 5))
508```
509
510## Group rows via multi-row cell
Hao Zhu72917f92019-03-15 18:41:42 -0400511Function `pack_rows` is great for showing simple structural information on rows but sometimes people may need to show structural information with multiple layers. When it happens, you may consider to use `collapse_rows` instead, which will put repeating cells in columns into multi-row cells. The vertical allignment of the cell is controlled by `valign` with default as "top".
Hao Zhu53e240f2017-09-04 20:04:29 -0400512
513```{r}
514collapse_rows_dt <- data.frame(C1 = c(rep("a", 10), rep("b", 5)),
515 C2 = c(rep("c", 7), rep("d", 3), rep("c", 2), rep("d", 3)),
516 C3 = 1:15,
517 C4 = sample(c(0,1), 15, replace = TRUE))
Hao Zhu3e21ff92020-08-20 08:24:07 -0400518kbl(collapse_rows_dt, align = "c") %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400519 kable_paper(full_width = F) %>%
Hao Zhu53e240f2017-09-04 20:04:29 -0400520 column_spec(1, bold = T) %>%
Hao Zhu6107f372018-05-21 00:23:26 -0400521 collapse_rows(columns = 1:2, valign = "top")
Hao Zhu53e240f2017-09-04 20:04:29 -0400522```
523
524# Table Footnote
Hao Zhu6a076462017-03-01 12:59:01 -0500525
Hao Zhub9da01c2018-01-14 21:01:57 -0500526> Now it's recommended to use the new `footnote` function instead of `add_footnote` to make table footnotes.
527
528Documentations for `add_footnote` can be found [here](http://haozhu233.github.io/kableExtra/legacy_features#add_footnote).
529
530There are four notation systems in `footnote`, namely `general`, `number`, `alphabet` and `symbol`. The last three types of footnotes will be labeled with corresponding marks while `general` won't be labeled. You can pick any one of these systems or choose to display them all for fulfill the APA table footnotes requirements.
Hao Zhu6a076462017-03-01 12:59:01 -0500531```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400532kbl(dt, align = "c") %>%
533 kable_classic(full_width = F) %>%
Hao Zhub9da01c2018-01-14 21:01:57 -0500534 footnote(general = "Here is a general comments of the table. ",
535 number = c("Footnote 1; ", "Footnote 2; "),
536 alphabet = c("Footnote A; ", "Footnote B; "),
537 symbol = c("Footnote Symbol 1; ", "Footnote Symbol 2")
538 )
Hao Zhu6a076462017-03-01 12:59:01 -0500539```
540
Hao Zhu6107f372018-05-21 00:23:26 -0400541You can also specify title for each category by using the `***_title` arguments. Default value for `general_title` is "Note: " and "" for the rest three. You can also change the order using `footnote_order`. You can even display footnote as chunk texts (default is as a list) using `footnote_as_chunk`. The font format of the titles are controlled by `title_format` with options including "italic" (default), "bold" and "underline".
Hao Zhub9da01c2018-01-14 21:01:57 -0500542
Hao Zhu6a076462017-03-01 12:59:01 -0500543```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400544kbl(dt, align = "c") %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400545 kable_paper(full_width = F) %>%
Hao Zhub9da01c2018-01-14 21:01:57 -0500546 footnote(general = "Here is a general comments of the table. ",
547 number = c("Footnote 1; ", "Footnote 2; "),
548 alphabet = c("Footnote A; ", "Footnote B; "),
549 symbol = c("Footnote Symbol 1; ", "Footnote Symbol 2"),
550 general_title = "General: ", number_title = "Type I: ",
551 alphabet_title = "Type II: ", symbol_title = "Type III: ",
Hao Zhu6107f372018-05-21 00:23:26 -0400552 footnote_as_chunk = T, title_format = c("italic", "underline")
Hao Zhub9da01c2018-01-14 21:01:57 -0500553 )
Hao Zhu6a076462017-03-01 12:59:01 -0500554```
555
Hao Zhub9da01c2018-01-14 21:01:57 -0500556If you need to add footnote marks in table, you need to do it manually (no fancy) using `footnote_mark_***()`. Remember that similar with `cell_spec`, you need to tell this function whether you want it to do it in `HTML` (default) or `LaTeX`. You can set it for all using the `knitr.table.format` global option. ALso, if you have ever use `footnote_mark_***()`, you need to put `escape = F` in your `kable` function to avoid escaping of special characters.
Hao Zhu53e240f2017-09-04 20:04:29 -0400557
Hao Zhu6a076462017-03-01 12:59:01 -0500558```{r}
Hao Zhub9da01c2018-01-14 21:01:57 -0500559dt_footnote <- dt
560names(dt_footnote)[2] <- paste0(names(dt_footnote)[2],
561 footnote_marker_symbol(1))
562row.names(dt_footnote)[4] <- paste0(row.names(dt_footnote)[4],
563 footnote_marker_alphabet(1))
Hao Zhu3e21ff92020-08-20 08:24:07 -0400564kbl(dt_footnote, align = "c",
Hao Zhub9da01c2018-01-14 21:01:57 -0500565 # Remember this escape = F
566 escape = F) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400567 kable_paper(full_width = F) %>%
Hao Zhub9da01c2018-01-14 21:01:57 -0500568 footnote(alphabet = "Footnote A; ",
569 symbol = "Footnote Symbol 1; ",
570 alphabet_title = "Type II: ", symbol_title = "Type III: ",
571 footnote_as_chunk = T)
Hao Zhu6a076462017-03-01 12:59:01 -0500572```
Hao Zhuf9aa4c42017-05-22 15:53:35 -0400573
Hao Zhu53e240f2017-09-04 20:04:29 -0400574# HTML Only Features
575## Scroll box
576If you have a huge table and you don't want to reduce the font size to unreadable, you may want to put your HTML table in a scroll box, of which users can pick the part they like to read. Note that scroll box isn't printer friendly, so be aware of that when you use this feature.
Hao Zhuf9aa4c42017-05-22 15:53:35 -0400577
Hao Zhu53e240f2017-09-04 20:04:29 -0400578When you use `scroll_box`, you can specify either `height` or `width`. When you specify `height`, you will get a vertically scrollable box and vice versa. If you specify both, you will get a two-way scrollable box.
Hao Zhu4c4bf8d2017-07-03 19:38:11 -0400579
580```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400581kbl(cbind(mtcars, mtcars)) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400582 kable_paper() %>%
Hao Zhu53e240f2017-09-04 20:04:29 -0400583 scroll_box(width = "500px", height = "200px")
Hao Zhu4c4bf8d2017-07-03 19:38:11 -0400584```
Hao Zhu6107f372018-05-21 00:23:26 -0400585
586<br>
587
588You can also specify width using a percentage.
589
590```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400591kbl(cbind(mtcars, mtcars)) %>%
Hao Zhu72917f92019-03-15 18:41:42 -0400592 add_header_above(c("a" = 5, "b" = 18)) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400593 kable_paper() %>%
Hao Zhu6107f372018-05-21 00:23:26 -0400594 scroll_box(width = "100%", height = "200px")
595```
596
Hao Zhu72917f92019-03-15 18:41:42 -0400597Starting from version 1.1.0, if you have a fixed-height box, the header row is fixed
598
Hao Zhu6107f372018-05-21 00:23:26 -0400599## Save HTML table directly
600If you need to save those HTML tables but you don't want to generate them through rmarkdown, you can try to use the `save_kable()` function. You can choose whether to let those HTML files be self contained (default is yes). Self contained files packed CSS into the HTML file so they are quite large when there are many.
601```{r, eval=FALSE}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400602kbl(mtcars) %>%
Hao Zhu5fe235c2020-08-26 00:26:49 -0400603 kable_paper() %>%
Hao Zhu6107f372018-05-21 00:23:26 -0400604 save_kable(file = "table1.html", self_contained = T)
605```
606
Hao Zhu3e21ff92020-08-20 08:24:07 -0400607## Use it with sparkline
608Well, this is not a feature but rather a documentation of how to use the `sparkline` package together with this package. The easiest way is sort of a hack. You can call `sparkline::sparkline(0)` somewhere on your document where no one would mind so its dependencies could be loaded without any hurdles. Then you use `sparkline::spk_chr()` to generate the text. For a working example, see: [Chinese names in US babynames](https://cranky-chandrasekhar-cfefcd.netlify.app/)
609
Hao Zhu9399dcc2020-08-26 17:27:38 -0400610```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400611# Not evaluated
612library(sparkline)
613sparkline(0)
614```
615
Hao Zhu9399dcc2020-08-26 17:27:38 -0400616```{r}
Hao Zhu3e21ff92020-08-20 08:24:07 -0400617spk_dt <- data.frame(
618 var = c("mpg", "wt"),
619 sparkline = c(spk_chr(mtcars$mpg), spk_chr(mtcars$wt))
620)
621
622kbl(spk_dt, escape = F) %>%
623 kable_paper(full_width = F)
624```
625
Hao Zhu6107f372018-05-21 00:23:26 -0400626# From other packages
627Since the structure of `kable` is relatively simple, it shouldn't be too difficult to convert HTML or LaTeX tables generated by other packages to a `kable` object and then use `kableExtra` to modify the outputs. If you are a package author, feel free to reach out to me and we can collaborate.
628
629## `tables`
Hao Zhuec169362018-05-21 01:05:29 -0400630The latest version of [`tables`](https://CRAN.R-project.org/package=tables) comes with a `toKable()` function, which is compatiable with functions in `kableExtra` (>=0.9.0).
Hao Zhua171b452019-01-15 17:14:34 -0600631
632## `xtable`
633For `xtable` users, if you want to use `kableExtra` functions on that, check out this `xtable2kable()` function shipped with kableExtra 1.0.
634
635```{r, eval=F}
636# Not evaluating
637xtable::xtable(mtcars[1:4, 1:4], caption = "Hello xtable") %>%
638 xtable2kable() %>%
639 column_spec(1, color = "red")
640```