Skip to contents

When creating R markdown pages and websites it can be useful to organise content into a grid of links and image, sometimes known as “cards”. To design a course website you may want something like this:

Starting R markdown

An introduction to R markdown. The target audience is a novice R user with no previous experience with markdown.

Starting ggplot2

An introduction to ggplot2. The target audience is a novice user with no previous experience with R or ggplot2.

Starting programming

This is primarily a tutorial on making generative art in R, but in doing so introduces core programming constructs and data structures. It is assumed the user has some previous experience with ggplot2.

Enabling bootstrap 4

The first step in using the package is to make sure that your R markdown document uses version 4 of bootstrap. The default behaviour of R markdown when creating HTML documents is to use bootstrap version 3, so this setting needs to be altered. To ensure that you are using bootstrap 4, you need to edit the YAML header for your document to specify which version of bootstrap you want to use. For a plain R markdown document or website (i.e., one where the output format is html_document) here is the relevant section of YAML you might use:

      version: 4

For other kinds of R markdown documents, see the enabling bootstrap article.

The galleries data

The main function in bs4cards is cards(). It takes a data frame as the first argument, generally the data set from which the bootstrap cards are to be constructed. The package comes with a data set galleries that I’ll use to create the grids

#> # A tibble: 7 × 7
#>   long_name  short_name  date   blurb     paintbrushes image_url   gallery_url  
#>   <chr>      <chr>       <chr>  <chr>     <chr>        <chr>       <chr>        
#> 1 Ash Cloud… ash         2021-… Simulate… ggplot2      https://bs… https://art.…
#> 2 Ghosts on… ghosts      2021-… Abstract… ambient      https://bs… https://art.…
#> 3 Ice Floes  ice-floes   2021-… Abstract… ambient      https://bs… https://art.…
#> 4 Native Fl… native-flo… 2021-… Collecti… ggplot2; fl… https://bs… https://art.…
#> 5 Silhouett… silhouettes 2021-… Trees ge… ggplot2; rc… https://bs… https://art.…
#> 6 Track Mar… track-marks 2020-… Voronoi … ggplot2; rc… https://bs… https://art.…
#> 7 Viewports  viewports   2021-… Simple m… ggplot2; fl… https://bs… https://art.…

Each row in this data corresponds to one card in the grid. The columns contain information that is useful for constructing the cards.

Basic usage

For example to create the card grid shown at the start of the vignette, I needed to the title for each card, the text printed below it, the image decorating the card, and the URL to which the title and image in each card should link. Each of these is an argument to cards(), and for each argument you can pass an expression that will be evaluated using the data input:

galleries %>% 
    title = long_name,
    link = gallery_url,
    image = image_url,
    footer = paste("posted:", date)

Additional example

The cards() function supports a variety of different layouts and customisation options, discussed in the next article. To give a flavour of what’s possible, here’s another example based on the same data:

galleries %>% 
    title = long_name,
    text = blurb,
    link = gallery_url,
    image = image_url,
    tags = paste("all;", paintbrushes),
    footer = paintbrushes,
    layout = "label-right", 
    width = 4,
    border_radius = 5

Ash Cloud and Blood

Simulated watercolours in ggplot2 using the transparent polygon method

Ghosts on Marble Paper

Abstract landscapes generated using ambient

Ice Floes

Abstract icebergs generated using ambient

Native Flora

Collections of small flametrees that resemble branching plants


Trees generated in flametree with random walk backgrounds

Track Marks

Voronoi tessellations with seed points sampled from an iterated function system


Simple masks with ggfx using flametree-generated textures

Where to next?

If you’re interested in using the bs4cards package, check out the articles page.