The kable() function in knitr is a very simple table generator, and is simple by design. It only generates tables for strictly rectangular data such as matrices and data frames. You cannot heavily format the table cells or merge cells. However, this function does have a large number of arguments for you to customize the appearance of tables:

  1. kable(x, format, digits = getOption("digits"), row.names = NA,
  2. col.names = NA, align, caption = NULL, label = NULL,
  3. format.args = list(), escape = TRUE, ...)

Supported table formats

In most cases, knitr::kable(x) may be enough if you only need a simple table for the data object x. The format argument is automatically set according to the knitr source document format. Its possible values are pipe (tables with columns separated by pipes), simple (Pandoc’s simple tables), latex (LaTeX tables), html (HTML tables), and rst (reStructuredText tables). For R Markdown documents, kable() uses the pipe format for tables by default, which looks like this:

  1. knitr::kable(head(mtcars[, 1:4]), "pipe")
mpg cyl disp hp
Mazda RX4 21.0 6 160 110
Mazda RX4 Wag 21.0 6 160 110
Datsun 710 22.8 4 108 93
Hornet 4 Drive 21.4 6 258 110
Hornet Sportabout 18.7 8 360 175
Valiant 18.1 6 225 105

You can also generate simple tables, or tables in HTML, LaTeX, and reStructuredText:

  1. knitr::kable(head(mtcars[, 1:4]), "simple")
  2. mpg cyl disp hp
  3. ------------------ ----- ---- ----- ----
  4. Mazda RX4 21.0 6 160 110
  5. Mazda RX4 Wag 21.0 6 160 110
  6. Datsun 710 22.8 4 108 93
  7. Hornet 4 Drive 21.4 6 258 110
  8. Hornet Sportabout 18.7 8 360 175
  9. Valiant 18.1 6 225 105
  10. knitr::kable(mtcars[1:2, 1:2], "html")
  11. <table>
  12. <thead>
  13. <tr>
  14. <th style="text-align:left;"> </th>
  15. <th style="text-align:right;"> mpg </th>
  16. <th style="text-align:right;"> cyl </th>
  17. </tr>
  18. </thead>
  19. <tbody>
  20. <tr>
  21. <td style="text-align:left;"> Mazda RX4 </td>
  22. <td style="text-align:right;"> 21 </td>
  23. <td style="text-align:right;"> 6 </td>
  24. </tr>
  25. <tr>
  26. <td style="text-align:left;"> Mazda RX4 Wag </td>
  27. <td style="text-align:right;"> 21 </td>
  28. <td style="text-align:right;"> 6 </td>
  29. </tr>
  30. </tbody>
  31. </table>
  32. knitr::kable(head(mtcars[, 1:4]), "latex")
  33. \begin{tabular}{l|r|r|r|r}
  34. \hline
  35. & mpg & cyl & disp & hp\\
  36. \hline
  37. Mazda RX4 & 21.0 & 6 & 160 & 110\\
  38. \hline
  39. Mazda RX4 Wag & 21.0 & 6 & 160 & 110\\
  40. \hline
  41. Datsun 710 & 22.8 & 4 & 108 & 93\\
  42. \hline
  43. Hornet 4 Drive & 21.4 & 6 & 258 & 110\\
  44. \hline
  45. Hornet Sportabout & 18.7 & 8 & 360 & 175\\
  46. \hline
  47. Valiant & 18.1 & 6 & 225 & 105\\
  48. \hline
  49. \end{tabular}
  50. knitr::kable(head(mtcars[, 1:4]), "rst")
  51. ================= ==== === ==== ===
  52. \ mpg cyl disp hp
  53. ================= ==== === ==== ===
  54. Mazda RX4 21.0 6 160 110
  55. Mazda RX4 Wag 21.0 6 160 110
  56. Datsun 710 22.8 4 108 93
  57. Hornet 4 Drive 21.4 6 258 110
  58. Hornet Sportabout 18.7 8 360 175
  59. Valiant 18.1 6 225 105
  60. ================= ==== === ==== ===

Please note that only the formats pipe and simple are portable, i.e., they work for any output document format. Other table formats only work for specific output formats, e.g., format = 'latex' only works for LaTeX output documents. Using a specific table format will give you more control, at the price of sacrificing portability.

If you only need one table format that is not the default format for a document, you can set the global R option knitr.table.format, e.g.,

  1. options(knitr.table.format = "latex")

This option can also be a function that returns the format string or NULL. In the case of NULL, knitr will try to automatically decide the appropriate format. For example, we can use the latex format only when the output format is LaTeX:

  1. options(knitr.table.format = function() {
  2. if (knitr::is_latex_output())
  3. "latex" else "pipe"
  4. })

Change column names

The names of columns in a data frame may not be the same as what we want to display to readers. In R, the column names of data often do not use spaces to separate words but dots or underscores instead. This may not feel natural when we read them in a table. We can use the col.names argument to replace the column names with a vector of new names. For example, we substitute the dots with spaces in the column names of the iris data:

  1. iris2 <- head(iris)
  2. knitr::kable(iris2, col.names = gsub("[.]", " ", names(iris)))
Sepal Length Sepal Width Petal Length 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

The col.names argument can take an arbitrary character vector (not necessarily the modified column names via functions like gsub()), as long as the length of the vector is equal to the number of columns of the data object, e.g.,

  1. knitr::kable(
  2. iris,
  3. col.names = c('We', 'Need', 'Five', 'Names', 'Here')
  4. )

Specify column alignment

To change the alignment of the table columns, you can use either a vector of values consisting of characters l (left), c (center), and r (right) or a single multi-character string for alignment, so kable(..., align = c('c', 'l')) can be shortened to kable(..., align = 'cl'). By default, numeric columns are right-aligned, and other columns are left-aligned. Here is an example:

  1. # left, center, center, right, right
  2. knitr::kable(iris2, align = "lccrr")
Sepal.Length Sepal.Width Petal.Length 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

Add a table caption

You can add a caption to the table via the caption argument, e.g. (see Table 10.1 for the output),

  1. knitr::kable(iris2, caption = "An example table caption.")

TABLE 10.1: An example table caption.

Sepal.Length Sepal.Width Petal.Length 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

As we mentioned in Section 4.7, a table can be cross-referenced when it has a caption and the output format is from bookdown.

Format numeric columns

You can set the maximum number of decimal places via the digits argument (which will be passed to the round() function), and other formatting arguments via format.args (to be passed to the format() function in base R). First we show a few simple examples of round() and format() so you will understand how the arguments work later in kable():

  1. round(1.234567, 0)
  2. ## [1] 1
  3. round(1.234567, digits = 1)
  4. ## [1] 1.2
  5. round(1.234567, digits = 3)
  6. ## [1] 1.235
  7. format(1000, scientific = TRUE)
  8. ## [1] "1e+03"
  9. format(10000.123, big.mark = ",")
  10. ## [1] "10,000"

Then we round and format numbers in a table:

  1. d <- cbind(X1 = runif(3), X2 = 10^c(3, 5, 7), X3 = rnorm(3,
  2. 0, 1000))
  3. # at most 4 decimal places
  4. knitr::kable(d, digits = 4)
X1 X2 X3
0.0698 1e+03 -571.9407
0.7653 1e+05 -2161.6849
0.0049 1e+07 -1705.9400
  1. # round columns separately
  2. knitr::kable(d, digits = c(5, 0, 2))
X1 X2 X3
0.06975 1e+03 -571.94
0.76528 1e+05 -2161.68
0.00491 1e+07 -1705.94
  1. # do not use the scientific notation
  2. knitr::kable(d, digits = 3, format.args = list(scientific = FALSE))
X1 X2 X3
0.070 1000 -571.941
0.765 100000 -2161.685
0.005 10000000 -1705.940
  1. # add commas to big numbers
  2. knitr::kable(d, digits = 3, format.args = list(big.mark = ",",
  3. scientific = FALSE))
X1 X2 X3
0.070 1,000 -571.941
0.765 100,000 -2,161.685
0.005 10,000,000 -1,705.940

Display missing values

By default, missing values (i.e., NA) are displayed as the character string NA in the table. You can replace them with other values or choose not to display anything (i.e., leave the NA cells empty) with the global R option knitr.kable.NA, e.g., we make NA cells empty in the second table and display ** in the third table below:

  1. d[rbind(c(1, 1), c(2, 3), c(3, 2))] <- NA
  2. knitr::kable(d) # NA is displayed by default
X1 X2 X3
NA 1e+03 -571.9
0.7653 1e+05 NA
0.0049 NA -1705.9
  1. # replace NA with empty strings
  2. opts <- options(knitr.kable.NA = "")
  3. knitr::kable(d)
X1 X2 X3
1e+03 -571.9
0.7653 1e+05
0.0049 -1705.9
  1. options(knitr.kable.NA = "**")
  2. knitr::kable(d)
X1 X2 X3
** 1e+03 -571.9
0.7653 1e+05 **
0.0049 ** -1705.9
  1. options(opts) # restore global R options

Escape special characters

If you are familiar with HTML or LaTeX, you know that there are a few special characters in these languages. To generate safe output, kable() will escape these special characters by default via the argument escape = TRUE, which means all characters will be generated verbatim, and special characters lose their special meanings. For example, > will be substituted with &gt; for HTML tables, and _ will be escaped as \_ for LaTeX tables. If you are an expert and know how to use special characters properly, you may disable this argument via escape = FALSE. In the second table below, we include a few LaTeX math expressions that contain special characters $, \, and _:

  1. m <- lm(dist ~ speed, data = cars)
  2. d <- coef(summary(m))
  3. knitr::kable(d)
Estimate Std. Error t value Pr(>\ t\ )
(Intercept) -17.579 6.7584 -2.601 0.0123
speed 3.932 0.4155 9.464 0.0000
  1. # add a few math expressions to row and column names
  2. rownames(d) <- c("$\\beta_0$", "$\\beta_1$")
  3. colnames(d)[4] <- "$P(T > |t|)$"
  4. knitr::kable(d, escape = FALSE)
Estimate Std. Error t value (P(T > |t|))
(beta_0) -17.579 6.7584 -2.601 0.0123
(beta_1) 3.932 0.4155 9.464 0.0000

Without escape = FALSE, special characters will either be escaped or substituted. For example, $ is escaped as \$, _ is escaped as \_, and \ is substituted with \textbackslash{}:

  1. knitr::kable(d, format = "latex", escape = TRUE)
  2. \begin{tabular}{l|r|r|r|r}
  3. \hline
  4. & Estimate & Std. Error & t value & \$P(T > |t|)\$\\
  5. \hline
  6. \$\textbackslash{}beta\_0\$ & -17.579 & 6.7584 & -2.601 & 0.0123\\
  7. \hline
  8. \$\textbackslash{}beta\_1\$ & 3.932 & 0.4155 & 9.464 & 0.0000\\
  9. \hline
  10. \end{tabular}

Other common special LaTeX characters include #, %, &, {, and }. Common special HTML characters include &, <, >, and ". You need to be cautious when generating tables with escape = FALSE, and make sure you are using the special characters in the right way. It is a very common mistake to use escape = FALSE and include % or _ in column names or the caption of a LaTeX table without realizing that they are special.

If you are not sure how to properly escape special characters, there are two internal helper functions in knitr. Below are some examples:

  1. knitr:::escape_latex(c("100%", "# a comment", "column_name"))
  2. ## [1] "100\\%" "\\# a comment" "column\\_name"
  3. knitr:::escape_html(c("<address>", "x = \"character\"",
  4. "a & b"))
  5. ## [1] "&lt;address&gt;"
  6. ## [2] "x = &quot;character&quot;"
  7. ## [3] "a &amp; b"

Multiple tables side by side

You can pass a list of data frames or matrices to kable() to generate multiple tables side by side. For example, Table 10.2 contains two tables generated from the code below:

  1. d1 <- head(cars, 3)
  2. d2 <- head(mtcars[, 1:3], 5)
  3. knitr::kable(
  4. list(d1, d2),
  5. caption = 'Two tables placed side by side.',
  6. booktabs = TRUE, valign = 't'
  7. )
TABLE 10.2: Two tables placed side by side.
speeddist
42
410
74
mpgcyldisp
Mazda RX421.06160
Mazda RX4 Wag21.06160
Datsun 71022.84108
Hornet 4 Drive21.46258
Hornet Sportabout18.78360

Please note that this feature only works for HTML and PDF output.

If you want to be able to customize each table individually when placing them side by side, you may use the kables() function (the plural form of kable()), and pass a list of kable() objects to it. For example, we change the column names in the left table and set the number of decimal places to zero in the right table in Table 10.3:

  1. # data objects d1 and d2 are from the previous code chunk
  2. knitr::kables(
  3. list(
  4. # the first kable() to change column names
  5. knitr::kable(
  6. d1, col.names = c('SPEED', 'DISTANCE'), valign = 't'
  7. ),
  8. # the second kable() to set the digits option
  9. knitr::kable(d2, digits = 0, valign = 't')
  10. ),
  11. caption = 'Two tables created by knitr::kables().'
  12. )
TABLE 10.3: Two tables created by knitr::kables().
SPEEDDISTANCE
42
410
74
mpgcyldisp
Mazda RX4216160
Mazda RX4 Wag216160
Datsun 710234108
Hornet 4 Drive216258
Hornet Sportabout198360

Generate multiple tables from a for-loop (*)

One common confusion about kable() is that it does not work inside for-loops. This problem is not specific to kable() but exists in many other packages, too. The reason is a little complicated. In case you are interested in the technicality, it is explained in the blog post “The Ghost Printer behind Top-level R Expressions.”

You may expect the following code chunk to generate three tables, but it will not:

  1. ```{r}
  2. for (i in 1:3) {
  3. knitr::kable(head(iris))
  4. }
  5. ```

You have to explicitly print the kable() results, and apply the chunk option results = 'asis', e.g.,

  1. ```{r, results='asis'}
  2. for (i in 1:3) {
  3. print(knitr::kable(head(iris)))
  4. }
  5. ```

In general, when you generate output from a for-loop, we recommend that you add a few line breaks (\n) or an HTML comment (<!-- -->) after each output element to clearly separate all output elements, e.g.,

  1. ```{r, results='asis'}
  2. for (i in 1:3) {
  3. print(knitr::kable(head(iris), caption = 'A caption.'))
  4. cat('\n\n<!-- -->\n\n')
  5. }
  6. ```

Without the separators, Pandoc may be fail to detect the individual elements. For example, when a plot is followed immediately by a table, the table will not be recognized:

  1. ![](logo.png)
  2. mpg cyl disp hp
  3. ------------------ ----- ---- ----- ----
  4. Mazda RX4 21.0 6 160 110
  5. Mazda RX4 Wag 21.0 6 160 110

But it will be if there is a clear separation like this (note that we added an empty line below the image):

  1. ![](logo.png)
  2. mpg cyl disp hp
  3. ------------------ ----- ---- ----- ----
  4. Mazda RX4 21.0 6 160 110
  5. Mazda RX4 Wag 21.0 6 160 110

or

  1. ![](logo.png)
  2. <!-- -->
  3. mpg cyl disp hp
  4. ------------------ ----- ---- ----- ----
  5. Mazda RX4 21.0 6 160 110
  6. Mazda RX4 Wag 21.0 6 160 110

Customize LaTeX tables (*)

If the only output format you need is LaTeX, there are a few extra options you can use in kable(). Note that these options will be ignored in other types of output such as HTML. Unless you have set the table format option globally (see Section 10.1.1), you will have to use the format argument of kable() explicitly in the examples of this section, e.g.,

  1. knitr::kable(iris2, format = "latex", booktabs = TRUE)

When you assign a caption to a table (see Section 10.1.4), kable() will use the table environment to include the table, i.e.,

  1. \begin{table}
  2. % the table body (usually the tabular environment)
  3. \end{table}

You can change this environment via the table.envir argument, e.g.,

  1. knitr::kable(cars[1:2, ], format = "latex", table.envir = "figure")
  2. \begin{figure}
  3. \begin{tabular}{r|r}
  4. \hline
  5. speed & dist\\
  6. \hline
  7. 4 & 2\\
  8. \hline
  9. 4 & 10\\
  10. \hline
  11. \end{tabular}
  12. \end{figure}

The floating position of the table is controlled by the argument position. For example, we can try to force a table to float to the bottom of a page via position = "!b":

  1. knitr::kable(cars[1:2, ], format = "latex", table.envir = "table",
  2. position = "!b")
  3. \begin{table}[!b]
  4. \begin{tabular}{r|r}
  5. \hline
  6. speed & dist\\
  7. \hline
  8. 4 & 2\\
  9. \hline
  10. 4 & 10\\
  11. \hline
  12. \end{tabular}
  13. \end{table}

When a table has a caption, you can also assign a short caption to it via the caption.short argument, e.g.,

  1. knitr::kable(iris2, caption = "A long long long caption!",
  2. caption.short = "A short one.")

The short caption goes into the square brackets of the \caption[]{} command in LaTeX, and is often used in the List of Tables of the PDF output document (if the short caption is not provided, the full caption is displayed there).

If you are familiar with the LaTeX package booktabs for publication-quality tables, you can set booktabs = TRUE, e.g.,

  1. iris3 <- head(iris, 10)
  2. knitr::kable(iris3, format = "latex", booktabs = TRUE)
  3. \begin{tabular}{rrrrl}
  4. \toprule
  5. Sepal.Length & Sepal.Width & Petal.Length & Petal.Width & Species\\
  6. \midrule
  7. 5.1 & 3.5 & 1.4 & 0.2 & setosa\\
  8. 4.9 & 3.0 & 1.4 & 0.2 & setosa\\
  9. 4.7 & 3.2 & 1.3 & 0.2 & setosa\\
  10. 4.6 & 3.1 & 1.5 & 0.2 & setosa\\
  11. 5.0 & 3.6 & 1.4 & 0.2 & setosa\\
  12. \addlinespace
  13. 5.4 & 3.9 & 1.7 & 0.4 & setosa\\
  14. 4.6 & 3.4 & 1.4 & 0.3 & setosa\\
  15. 5.0 & 3.4 & 1.5 & 0.2 & setosa\\
  16. 4.4 & 2.9 & 1.4 & 0.2 & setosa\\
  17. 4.9 & 3.1 & 1.5 & 0.1 & setosa\\
  18. \bottomrule
  19. \end{tabular}

Please note that when you need additional LaTeX packages such as booktabs for an R Markdown document, you have to declare these packages in YAML (see Section 6.4 for how).

Depending on whether the argument booktabs is TRUE or FALSE (default), the table appearance is different. For booktabs = FALSE:

  • Table columns are separated by vertical lines. You can explicitly remove the vertical lines via the vline argument, e.g., knitr::kable(iris, vline = "") (the default is vline = "|"). You can set this option as a global R option so you do not need to set it for every single table, e.g., options(knitr.table.vline = "").

  • The horizontal lines can be defined via arguments toprule, midrule, linesep, and bottomrule. Their default values are all \hline.

For booktabs = TRUE:

  • There are no vertical lines in the table, but you can add these lines via the vline argument.

  • The table only has horizontal lines for the table header and the bottom row. The default argument values are toprule = "\\toprule", midrule = "\\midrule", and bottomrule = "\\bottomrule". A line space is added to every five rows by default. This is controlled by the argument linesep, which defaults to c("", "", "", "", "\\addlinespace"). If you want to add a space to every three rows, you can do this:

    1. knitr::kable(iris3, format = "latex", linesep = c("", "",
    2. "\\addlinespace"), booktabs = TRUE)
    3. \begin{tabular}{rrrrl}
    4. \toprule
    5. Sepal.Length & Sepal.Width & Petal.Length & Petal.Width & Species\\
    6. \midrule
    7. 5.1 & 3.5 & 1.4 & 0.2 & setosa\\
    8. 4.9 & 3.0 & 1.4 & 0.2 & setosa\\
    9. 4.7 & 3.2 & 1.3 & 0.2 & setosa\\
    10. \addlinespace
    11. 4.6 & 3.1 & 1.5 & 0.2 & setosa\\
    12. 5.0 & 3.6 & 1.4 & 0.2 & setosa\\
    13. 5.4 & 3.9 & 1.7 & 0.4 & setosa\\
    14. \addlinespace
    15. 4.6 & 3.4 & 1.4 & 0.3 & setosa\\
    16. 5.0 & 3.4 & 1.5 & 0.2 & setosa\\
    17. 4.4 & 2.9 & 1.4 & 0.2 & setosa\\
    18. \addlinespace
    19. 4.9 & 3.1 & 1.5 & 0.1 & setosa\\
    20. \bottomrule
    21. \end{tabular}

    If you want to remove the line spaces altogether, you may use linesep = ''.

Sometimes your table may be longer than a page. In this case, you can use the argument longtable = TRUE, which uses the LaTeX package longtable to span your table to multiple pages.

Tables are center-aligned by default when they are included in a table environment (i.e., when the table has a caption). If you do not want to center a table, use the argument centering = FALSE.

Customize HTML tables (*)

If you want to customize tables generated via knitr::kable(format = "html"), there is only one extra argument besides the common arguments mentioned in previous sections: table.attr. This argument allows you to add arbitrary attributes to the <table> tag. For example:

  1. knitr::kable(mtcars[1:2, 1:2], table.attr = "class=\"striped\"",
  2. format = "html")
  3. <table class="striped">
  4. <thead>
  5. <tr>
  6. <th style="text-align:left;"> </th>
  7. <th style="text-align:right;"> mpg </th>
  8. <th style="text-align:right;"> cyl </th>
  9. </tr>
  10. </thead>
  11. <tbody>
  12. <tr>
  13. <td style="text-align:left;"> Mazda RX4 </td>
  14. <td style="text-align:right;"> 21 </td>
  15. <td style="text-align:right;"> 6 </td>
  16. </tr>
  17. <tr>
  18. <td style="text-align:left;"> Mazda RX4 Wag </td>
  19. <td style="text-align:right;"> 21 </td>
  20. <td style="text-align:right;"> 6 </td>
  21. </tr>
  22. </tbody>
  23. </table>

We added a class striped to the table. However, a class name is not enough to change the appearance of a table. You have to define CSS rules for the class. For example, to make a striped table that has different colors for odd and even rows, you can add a light gray background to even or odd rows:

  1. .striped tr:nth-child(even) { background: #eee; }

The above CSS rule means all rows (i.e., the <tr> tags) with even row numbers (:nth-child(even)) that are children of an element with the striped class will have a background color #eee.

A little bit of CSS can make a plain HTML table look decent. Figure 10.1 is a screenshot of an HTML table to which the following CSS rules are applied:

  1. table {
  2. margin: auto;
  3. border-top: 1px solid #666;
  4. border-bottom: 1px solid #666;
  5. }
  6. table thead th { border-bottom: 1px solid #ddd; }
  7. th, td { padding: 5px; }
  8. thead, tfoot, tr:nth-child(even) { background: #eee; }

Image 1: A striped table created with HTML and CSS.

FIGURE 10.1: A striped table created with HTML and CSS.