Check out a free preview of the full Intermediate Gatsby with Gatsby Themes course:
The "Theme UI Plugin" Lesson is part of the full, Intermediate Gatsby with Gatsby Themes course featured in this preview video. Here's what you'd learn in this lesson:

Jason demonstrates how to add the Gatsby theme UI plugin, how to access the theme UI props, and how to use the Gatsby sx property to improve the theme UI.

Get Unlimited Access Now

Transcript from the "Theme UI Plugin" Lesson

[00:00:00]
>> Jason Lengstorf: The next thing we wanna do is take our pretty bare bones, unstyled theme and give it some base styles, and give it some hook. So that people who'll use the theme are able to override those styles, and make it look like theirs. So let's go ahead and install what we need here.

[00:00:18] So we'll start in the gatsby-theme-docs workspace. And we will add, we're gonna add theme-UI. We're gonna add gatsby-plugin-theme-UI. And then there are a couple dependencies under the hood here. The first one is emotion/core. And then we also need mdx-js/react. Now we've already installed mdx-js/react. I'm just installing it as part of this to show the full suite of dependencies in case anybody skipped ahead.

[00:00:55] But it doesn't hurt to run it again. So, once we've got this in, we can go into our gatsby-config and we can just drop in gatsby-theme, or gatsby-plugin, sorry, plugin-theme-ui. And so we can see in our package.json, we've got the gatsby-plugin-theme-UI, and its dependencies. And our gatsby-config, we've got gatsby-plugin-theme-UI.

[00:01:25] And what this will do is it'll wrap the output of the site in a theme provider, so that different parts of our site are able to actually access that theme. To make this actually work, let's go in and modify a couple things. So the first thing we wanna do is let's get our layout to look nice.

[00:01:45] And I'm gonna do that by first, I wanna be able to use the theme UI shortcuts. It has a prop, like a convenience prop called SX, which lets us access the theme UI props and stuff. But to do that, we have to change the pragma. A pragma for those of you who aren't familiar with it is the way that React magically recognizes JSX and turns it into content.

[00:02:18] It's why React has to be in Scope when you create a component even if you don't ever actually reference the React import. So if we change our pragma, we no longer need React and Scope because we're providing a new create element function that will do basically all the same things that React does, but it adds extra functionality.

[00:02:39] In this case we're adding support for that SX prop. So to do that, I'm going to change our pragma to JSX. And then down here, I'm going to import JSX from Beam UI. And then because we don't need React anymore, I'm just gonna swap this out to fragment only.

[00:03:04] And we'll just simplify down like that. And I'm using fragments so that we don't get like empty wrapper divs. Fragment kind of compiles away and doesn't become actual markup, which keeps our websites a little more semantic, a little bit easier to reason about if you're looking at the source.

[00:03:23] So, now that we've got this pragma in here, what we can do is we can start adding some styles. And so the first thing that I wanna add is I'm just gonna add this SX prop to my header. And I wanna set the background. And so one of the things that's a little tricky at first about theme-UI, and then wonderful is that it has shortcut methods so that you don't have to type out really long property names.

[00:03:50] So instead of typing out background, I can just type bg. And I want the background of my header to be the primary color on my site. And we haven't defined these colors yet, so don't worry. We'll get to that in a second. I want the color of my header to be the background color of the site.

[00:04:10] I want the font family to be the heading font family. And I wanna set the padding, and because it's a common one, there's a shortcut, we can set the padding. I want the padding to be three. So I can set that and we can see here that it's just on the header as a prop, and this is a theme-UI shortcut for like theme-UI styles.

[00:04:35] Then on the main, I'm gonna add a few things as well. So I want to set this one to be, I only want the margin left and right to be auto so that it centers in the screen. But there's a shortcut for that as well. We can do margin x or left, right, and I'm gonna set that to auto.

[00:04:52] I'm gonna set the maxWidth to 650 pixels. I'm gonna set the width to 90, or 90 view port width units I think is what that's short for. And that'll prevent it from getting squished up against the sides on small view ports.