How to Create Your Own Table Theme with the gt Package

In our consulting work at R for the Rest of Us, we create tables all the time. We don’t just make plain tables, we make tables that look good and communicate well. This is important because:

1. A clean design is more convincing

2. A powerful design stands out so that people actually look at our tables

3. We can use colors to reflect our clients’ branding

We recently helped the Oregon Voices project to create customized data reports for every county in Oregon. Among other things, this required creating custom tables in their theme so that the tables match nicely with the design of their reports.

Designing a table and adding a corporate identity to the design can mean lots of time-consuming work. But here’s the good news: If you have styled your table once, then you can always reuse that theme. And the even better news: If you wrap all of that into your very own theme function, then it just takes one function call to transform any table into your design. Let me show you how that works.

An example with gt

In order to create a beautiful table design, we need a table first. So let’s create a very simple one. Of course, you can apply the same strategies on a very elaborate table. Here let’s just stick to something basic.

First, let us load the tidyverse and the gt package. We’ll use the latter package to create a table. Also, the gt package comes with many neat data sets that we can use to build a table. Here we’ll use its gtcars dataset to create a table on Ferraris.

We can see what the ferrari_data data looks like:

To turn this dataset into a table, we can just call gt().

Now, let’s format the column labels (with the cols_label() function) and add a title and subtitle (with the tab_header() function) to describe our data. This will be the table we’ll use to create a custom theme. So, we’ll save it for later use as well.

Here’s what the saved ferrari_table looks like:

Add a theme

Right now, our table is pretty boring because it’s a plain black-and-white table. So let’s transform this a little bit. First, we can change a lot of settings via the tab_options() function. What I´m doing here is

• changing the row height with data_row.padding,

• aligning the titles to the left with heading.align,

• adding a little bit of color to the table with column_labels.background.color,

• changing the font sizes with heading.title.font.size and heading.subtitle.font.size and

• removing the vertical lines with table_body.hlines.width.

Next, let’s change the title’s font and color. We can achieve this by using tab_style() to specify text properties via cell_text() on the title cells that we determine via cells_title().

At first, this may feel a bit confusing but once you get accustomed to using nested function calls to style your table it will feel very straightforward. And if you need to read up on this, you can find a thorough gt styling guide here.

Finally, we can make every other row grey by using tab_style() and cell_fill() on the corresponding rows in the table that we select via cells_body(). This requires using a vector that contains only every other row number. Such a vector can be computed with seq(1, nrow(ferrari_data), 2).

Our table is fully styled now. Even though it’s the exact same information as before, the table feels different, doesn’t it?

Create a reusable theme

So what if we want to reuse this theme? In principle, we can just drop all of the code into a reusable function. Let’s try that with everything except for making every other row grey (we’ll cover that soon enough).

Then, we could just apply our gt theme like so.

And of course this works with other gt tables too. Otherwise, this function wouldn’t really be reusable, wouldn’t it? So, here’s a new table I’ve created on the fly.

Here’s what the unstyled new_table looks like:

Once again, I can just apply my_gt_theme() to change the table’s style.

As you can see, with a custom theme function it’s easy to make any table have a similar look-and-feel.

Advanced section: Make your theme data-dependent

Now, if you’re up for it, we can do something more advanced: Let’s make our theme data-dependent. This is important because some styles require that you have some basic knowledge about the underlying data.

For example, we have already seen that making every other row grey required a vector that we have created with seq(1, nrow(ferrari_data), 2). Hence, our theme function should now the underlying data ferrari_data. To make this happen, we’re going to use a sneaky trick that I’ve picked up from Thomas Mock’s blog.

The trick is this: Every gt table also stores the original data and you can access it via $`data`. For example, if we call ferrari_table from before, this would just show us the table again. But if we use the $ operator to access data, then we get the underlying data.

Hence, we can use this in our custom theme function. This way, our theme function is reusable for all kinds of gt tables because our function can always grab the underlying data from the gt object.

Now we can use our modified function on our previous tables. Here’s how that looks for our Ferrari table.

Conclusion

Hooray! We’ve learned how to create our own theme and wrap it into a reusable function. This is an elegant way to make your tables more appealing. And if you’re looking for a bit of inspiration for your tables, you can always check out the themes from the gtExtras package.