Garrick Aden-Buie - Announcing xaringanthemer v0.3.0!

New Features and Now on CRAN! 🎉

This release has been a long time in the making, and I’m very excited to share with you all of the cool new things that xaringanthemer can bring to your xaringan slides!

I started working on one of the key features of this release about a year ago — ggplot2 themes that magically match your slide theme — but only recently was able to make the time to push the documentation and tests over the CRAN finish line. Equally exciting, xaringanthemer finally has it’s own hex logo thanks to critical artistic help from my amazingly talented sister Aubrey Aden-Buie!

This post walks through the purpose of xaringanthemer and all of the new features in version 0.3.0. You can try out xaringanthemer for your next presentation, right after you install the package:

install.packages("xaringanthemer")

What does xaringanthemer do?

xaringanthemer works hand-in-hand with xaringan, the R package that turns your R Markdown into beautiful HTML slides rendered as web pages using the remarkjs library.

xaringan slides tend to look like the slides below, and, by default, xaringan uses the default slide theme from remarkjs.

xaringan does come with a collection of user-contributed themes to choose from, but customizing any xaringan slide theme requires working with CSS and learning which CSS rules apply to each element in the slides.

Even if you love CSS, it can still be difficult and time-consuming to set up your slides to use a consistent color palette or custom fonts.

The magic of xaringanthemer is that it grants you the power to quickly set up a complete slide theme, starting from only one or two color choices. You pick how these color choices are applied by choosing from a collection of style_ functions, and you can tweak the default color choices easily by providing alternative values for many theme parameters.

These slides were styled using the style_duo_accent() function, which applied my primary color and my secondary color consistently throughout the slide theme.

You can also easily use fonts from Google Fonts by using the google_font() helper. I used eye-catching fonts in this example that I probably wouldn’t use in real life (the default fonts used by xaringanthemer are much more readable).

Here’s the complete code chunk that I used in my slides.Rmd file to create the example above.

```{r xaringan-themer, include=FALSE}
style_duo_accent(
  primary_color = "#035AA6",        # blue
  secondary_color = "#03A696",      # sea green
  header_font_google = google_font("Amatic SC"),
  text_font_google = google_font("Crete Round"),
  header_h1_font_size = "3.5rem",
  header_h2_font_size = "2.75rem"
)
```

The slide style functions come in a few flavors. Styles derived from two color choices are prefixed with style_duo_. Slide themes generated from a single color use the style_mono_ prefix. There are also two complete styles based on the solarized color palette: style_solarized_light() and style_solarized_dark(). And finally, you can use the style_xaringan() base theme function directly, which starts from the default xaringan theme.

All of the style_ functions write a CSS file containing your complete slide theme. By default, the file is called xaringan-themer.css and you can create your CSS file in a separate R script or you can include the style-generating code in your slides with a chunk like the one above.

In either case, in order for your slides to use your new theme, you need to modify the css argument of xaringan::moon_reader in the YAML header of your slides.

output:
  xaringan::moon_reader:
    css: xaringan-themer.css

That’s xaringanthemer in a nutshell! You can learn more about the features in the package below, or by visiting pkg.garrickadenbuie.com/xaringanthemer.

New Features

There are quite a lot of new features in version 0.3.0 that I’m very excited to share with you.

Consistent API with style functions

This package has been on GitHub for a couple of years, and thank you to everyone who tested and contributed to the development over the years.

If you’ve used the GitHub version before, the API has changed slightly, but there should not have been any breaking changes. In short, all of the files that write CSS, for example the functions previouslly called duo_accent() or write_xaringan_theme(), are now prefixed with style_, e.g. style_duo_accent() and style_xaringan().

Powered by CSS variables

xaringanthemer does much of the work on the R side to prepare the theme, but nearly all of the properties of your theme are stored in CSS variables (or custom properties). This makes it possible to re-use colors from your theme, either in custom CSS or as arguments to the style function parameters.

Whenever a theme parameter is stored in a CSS variable, the documentation of the associated argument in the style function will tell you what CSS variable name is used. For example, the link_color argument is made available in the CSS as var(--link-color).

In general, argument names are converted from snake_case_names to kebab-case-names.

Setting additional colors

If you’ve spent a lot of time picking out a color palette, or if you’re using a corporate color palette, you’ll likely have more than just two colors that you want to use, and possibly not just in the components of your theme.

The markdown syntax used by xaringan (actually remarkjs in this case) allows you to apply a class to text using syntax like this: .class[ ... ]

Building on the use of CSS variables, xaringanthemer helps you add these additional colors to your theme. Using the colors argument, you can specify a vector of named colors.

style_xaringan(
  colors = c(
    red = "#f34213",
    purple = "#3e2f5b",
    orange = "#ff8811",
    green = "#136f63",
    white = "#FFFFFF",
  )
)

The color names are then used in three places. Using the red color as an example, xaringanthemer adds

a CSS variable var(--red) that use anywhere in custom CSS
a .red class to set color: var(--red)
a .bg-red class setting background-color: var(--red).

The named color and background classes are then easy to use in xaringan. Slide text like this

This **.red[simple]** .white.bg-purple[demo]
_.orange[shows]_ the colors .green[in action].

will be rendered in HTML as

This simple demo shows the colors in action.

Matching ggplot2 themes

At this point your slides look a m a z i n g, but your ggplot2 plots stick out like a sore thumb with their sad shades of gray.

You want your data visualizations to have the same level of visual appeal as your hand-crafted slide theme, and xaringanthemer can help! I’ll quickly cover some of the new features for styling ggplots here, and you can learn more in the ggplot2 Themes vignette.

theme_xaringan()

xaringanthemer provides a ggplot2 theme that knows the styles used in your slides: theme_xaringan(). Let’s start with a basic, typical ggplot2 plot of fuel efficiency of cars using the ggplot2::mpg dataset. You only need to add + theme_xaringan() to give your plot a makeover.

library(ggplot2)

g_base <- ggplot(mpg) +
  aes(hwy, cty) +
  geom_point() +
  labs(x = "Highway MPG", y = "City MPG", title = "Fuel Efficiency")

# Basic plot with default theme
g_base

# Fancy slide-matching themed plot
g_base + theme_xaringan()

theme_xaringan() matches the colors used in your slides to the plot and axis titles (slide heading color) and axis tick labels and default text geometries (slide text color). It also uses the showtext by Yixuan Qiu to match the fonts used in your slides — this feature works particularly well when you use fonts from Google Fonts. theme_xaringan() also sets the default color, fill and text family aesthetics of many ggplot2 geoms, changing, for example, the color of points to match the primary slide color.

Our theme_xaringan() themed plot would fit right in on just about any slide in the slide deck we made with style_duo_accent() above, except for our inverse-styled slides…

theme_xaringan_inverse()

In xaringan, inverse slides provide a nice way to visually break up your presentation. You can create them using the inverse class:

---
class: inverse

<!-- slide content -->

xaringanthemer also provide a ggplot2 theme for these slides as well: theme_xaringan_inverse().

# theme_xaringan() on the left,
g_base + theme_xaringan()

# theme_xaringan_inverse() on the right
g_base + theme_xaringan_inverse()

Matching color and fill scales

To give your plots a little more visual appeal, xaringanthemer includes custom color and fill scales based on the primary slide color. This feature uses colorspace::sequential_hcl() from the colorspace package.

The scale functions all follow the naming pattern scale_xaringan_<aes>_<data_type>(), where <aes> is replaced with either color or fill and <data_type> is one of discrete or continuous. For colors scales matching the inverse slide style, set inverse = TRUE. Occasionally, you may want to use a different primary color to generate the color or fill scale using the color argument.

ggplot(diamonds, aes(x = cut)) +
  geom_bar(aes(fill = ..count..), show.legend = FALSE) +
  labs(x = NULL, y = "Count", title = "Diamond Cut Quality") +
  theme_xaringan() +
  scale_xaringan_fill_continuous()

ggplot(diamonds, aes(x = cut)) +
  geom_bar(aes(fill = ..count..), show.legend = FALSE) +
  labs(x = NULL, y = "Count", title = "Diamond Cut Quality") +
  theme_xaringan_inverse() +
  scale_xaringan_fill_continuous(color = "#F2B155")

Custom color with scale_xaringan_fill_continuous()

Three ways to use `theme_xaringan()`

In what is likely the most common scenario, theme_xaringan() learns the slide styles when you use any of the style functions in your slides’ source code.

Alternatively, you may want to create your CSS files in another process or to use a xaringanthemer CSS file that you share between presentations. In these cases, theme_xaringan() will find the CSS file if it’s in the same folder or a subdirectory of the folder containing your slides source .Rmd. If you have multiple CSS files, or your CSS file is stored elsewhere, you can use the css_file argument to tell theme_xaringan() which file to use. This also means that you can easily match the plots in other R Markdown reports or webpages with theme_xaringan() to the styles used in your presentations by point css_file to the styles used in your slides.

Finally, you can create themes without calling a style function or a CSS file using the theme_xaringan_base() function. This theme function can be used for complete ggplot2 themes, including Google Fonts. (Note that the text_font and title_font arguments can take a google_font() in all theme_xaringan_ functions.)

ggplot(diamonds, aes(x = cut)) +
  geom_bar() +
  labs(x = NULL, y = NULL, title = "Diamond Cut Quality") +
  ylim(0, 25000) +
  theme_xaringan_base(
    title_font = google_font("Merriweather", 800),
    title_font_size = 20,
    text_font = google_font("PT Sans"),
    text_font_size = 16,
    background_color = "#FFFFFF",
    text_color = "#444444",
    accent_color = "#002B36",
  ) +
  theme(plot.title = element_text(face = "bold"))

A plot with theme_xaringan_base() styled to match this blog

Learning more about ggplot2 themes

To learn more about the ggplot2 themes, you can reference the ggplot2 themes vignette online or with vignettes("ggplot2-themes").

Other new things

There are a few other new features that are worth a quick mention.

Header background

If you like the metropolis theme in xaringan — ported from the classic beamer theme by Patrick Schratz who has a demo slide deck on his site — then you might like the header background feature that brings the title bar background to any xaringan presentation.

The background is applied to the first level-1 heading on the slide — either <h1>Title</h1> or # Title. There are two modes to the header background: auto and manual.

Manual mode is the default, meaning that for any xaringanthemer slides you can enable the header background using the header_background slide class:

---
class: header_background

# Title with a background

<!-- slide content -->

Auto mode is invoked by setting header_background_auto = TRUE in the style functions which makes the first level-1 heading of all normal slides into title background. In auto mode, you can disable the header background manually by using class: normal. The header background isn’t applied to title or inverse slides, slides where the text is aligned middle or bottom, or slides with the normal class.

New default fonts

While the default xaringan fonts are eye-catching and interesting when you first see them, I personally think that they don’t work well in low-visibility settings, like presentations made in person. xaringanthemer therefore uses a different set of default fonts: Cabin for headings and Noto Sans for body text.

A Cabin in the Clearing

Pack my box with five dozen liquor jugs. Amazingly few discotheques provide jukeboxes.

These fonts are easier to read on screens and at a distance during presentations, and they support a wide variety of languages and weights. Another reason for the change is that the xaringan (remarkjs) default body font, Droid Serif, is no longer officially included in Google Fonts.

Thanks

Thanks to everyone who sumbitted pull requests, issues, or comments: @Btibert3, @Northbreeze, @pat-s, @PMassicotte, @techisdead, and @TrashBirdEcology

Thanks to Aubrey Aden-Buie for help designing the xaringanthemer hex logo!