Type-safe Styling for React Component Packages: Vanilla Extract CSS

Have you ever found yourself wrestling with CSS in a React application and thinking, there's got to be a better way? Sounds familiar, right? Today we're going to talk about the type-safe styling method in React applications.

Hi, my name is Negar Jamwani-Farad. I'm a software developer at Lightspeed Commerce, and my friends and colleagues know me for my passion for CSS and working on design systems. And today, I'm going to talk about one of the things that recently caught my attention. I'm going to start with a quick comparison between some of the most popular tools for styling in React, like CSS in JS in general, CSS modules, and this new kit on the blog, Vanilla Extracts CSS. And trust me, by the end of this, you're going to have a new favorite.

You might wonder, we already have so many great options. I mean, who doesn't like CSS in JS? Well, it is popular indeed. It offers scoped styling right inside the component, and it also has good developer experience with no context switching when you're going back and forth between your CSS and styling files, between your JS and styling files. But it all comes with some costs. It has some runtime overload, and if your application is very large, you're going to end up with a large JS bundle file.

Now we have CSS modules. It also offers scoped styling. It compiles down to plain CSS, which means no runtime overhead and a smaller JS bundle size. But to be fair, the developer experience is not as good as CSS and JS solutions, especially when TypeScript is in the game. And now, enters vanilla extract CSS. Think of it as a package that marries the best of both worlds, a scoped styling, zero runtime overhead, and providing great developer experience with a CSS and TS, a beautiful syntax. So for a design system component package which needs efficiency, scalability, and maintainability, we want both performance and good developer experience. And in my opinion, vanilla extract CSS is an option worth considering.

So let's dive into why vanilla extract is turning so many heads around. So I mentioned zero runtime. Vanilla extract generates a static CSS file at build time, so it has no runtime overhead, and as a result, it has better performance. It is framework agnostic. So you develop your styles once, and then you can use it across different libraries, whether it's React, Vue, or whatever new library your team suddenly decided to use. It has a very powerful toolkit. You're thinking about Tailwinds because of its utility classes. Well, Vanilla Extract's CSS has Sprinkles, and you might think of, Oh, but I need to do some calculation in my CSS. But Vanilla Extract offers CSS utils and some other tools that I'm going to talk about during the demo. It's also, on top of all of these features, has type safety. And with type safety, you can define themes with deeply nested tokens and let the TypeScript to take care of all of that.

Or auto-complete, and not missing out token change somewhere in your application. So I think I talked a lot about Vanilla Extract so far. Let's jump into code and see it in practice, and see what it is all about.

So let me switch to my editor, here. So here I have a very simple React application. I've created this with Vite. It's TypeScript, React, and Vite as a bundler. I've created a very, very simple button component, here. We're going to mimic creating components in design system component packages, and I'm going to try my best that in a very short time, create themes, add variation to this button, and I'll add all the styling to this button. So right now if you want to check out the component, it looks like this. It's basically the basic HTML button.

So we have to start with adding vanilla extract CSS. To start that, there are two packages that we need to install. And one of them is vanilla extract itself, and the other one is recipe. I'm going to talk about recipe later in this talk. But I have them right now installed just for the sake of time, so we don't have to install them.

So another package that you need to start at the beginning of a project is a bundler. And vanilla extract CSS offers a couple of bundler integrations with different platforms. Right now, I'm using Vit, so I need to install a Vit Bundler plugin to be able to bundle our CSS files at the build time. So to configure that, we need to head over to vit.config and, as you can see, I've already done it, you import the plugin and then add it to your Vit config. And as simple as that, you're all set. You have everything set up to start writing your stuff. So the first thing I'm going to create is a very basic setting for my button so it's not just the boring HTML button. So in my component folder, I'm going to add a button.css.ts file, and that's why we need the bundler. And I'm going to create, I'm going to call it button style, oh my god, I hate live coding. So there is a style function in vanilla CSS that we're going to use here. And for the sake of time, I'm just going to copy and paste from my notes the styling that I have created for this component. So very basic styling, like hover and focus and everything. And we need to export this from this file. And then, now we head back to our button, and here for the class name, I'm going to export the button style that I exported in my other file.

Very similar to what we do in CSS modules. So now let's have a look at it in the browser, and as you can see, this file has been applied, and as simple as that.

Okay, now I want to add some colors and some borders to my button, but I don't want to just hard code these values into my CSS. I want to use the values coming from a theme. So we need to create a theme. So I have created a theme.css.ts file. And in this file, I'm going to create a default theme, and I'm going to use another function from vanilla Extract CSS, which is called create theme, very intuitive. And in this file, I'm going to pass in the tokens I want to have for my theme. So I have a very simplified token structure here ready for the sake of demo. It only has like two colors, but it can be the whole theme that you want for your application. What create theme here does for us is that it creates CSS variables for every single of these tokens, and then wraps these values with a class. And this class is exposed here as, I'm going to call it default theme class. And then as second parameter, it also returns a var. I like to call it a var. And this is actually a data structure following the exact structure that we provided in our token here. And then we can use it in our styling to get these values in my, for example, button.css.ts5.

So now we have so far one theme for our application. But let's just go beyond that and add another color. So let's say I want to have another pink theme. And I'm going to use the same create theme function, but this time as first parameter I'm going to pass in vars because I don't want to, I want to follow the same pattern. So this is the way, this is how we tell, when you're going to extract CSS, that I'm going to follow the same structure. And as second parameter, I'm going to pass in my new values that's going to overwrite the previous one. So here, I'm going to pass in my pink theme values. So I need to export all of these values at the end. So I have a default class, I have a pink theme class, and then I have my vars. And then I have created, my whole application is wrapped by a component called themeSweepter. It's just a simple component that switches the class on top level from one theme to another so that we can... Let's see, probably I had some typo... Okay. And okay, let's head back to our component.

So as you can see, this part has added but it's not working because we're not using the values of the theme. So I go back to my button.css.ts and for the background color, I'm going to import the vars that I exported there in my theme and here I'm going to say pick the colors primary and main. And I'm going to use another one here. So I want the color black. Look at that. Autocomplete. Oh my god. It's so exciting. So and then I'm going to use the dark theme for my hover and for my outline, I'm going to use another color. So I'm just going to go with grey and main. Now let's go back to our computer. Go to our browser and as you can see the theme has been applied and now let's switch theme. We have our two colors in two themes within a few minutes.

So in the component packages, it normally happens that we want to pass in a prop to our component like a variant, a type, a size, and then based on the prop that we pass to the component we want to be able to change our design and our styling of the component. So for that we need to use recipe. So to start implementing that I'm going to replace the style with the recipe function and I need to move all of these stylings under base. So it's going to be the basis styling of my component. So I'm going to comment out these because we are going to move them in another section and recipe provides a variant, oh sorry, I guess variance, yes. So variance can be anything from type to size, even it can be a boolean like disabled. So here I'm just going to create a type variant and I want my type variant to have a fill and then I want it to have outline. So these are going to be different types of my bun and I want a simple text type without any background or anything. So now we need to add all the styling for each and every of these types that is supposed to overwrite the base styling that we have up here. So I have it ready so I'm going to copy and paste it from my notes. So if I can, apparently, I use my ability to copy and paste. And the text. So here we go. It's just simply adding background and hover for each type. But there is one more thing that we need to do. We need to tell Banyuda Extract which one is our default variant. So we say, for default variants, for type, I want it to be fill. And since it's TypeScript, it's fully typed, so it has great suggestions. If we want to implement that into a button, normally what you should do is to add the type here, and then you need to add it to your props type, but then you have to follow the exact naming from your styling, and keeping these in sync over time is a hustle. So you got to go, type, I want it to be fill, and then blah, blah, and keeping that consistent over time is really hard, but you don't really have to do that with Vanilla Xtract, there is a tool, so I'm going to say, I'm going to export button variant, and I'm going to use recipe, recipe, help me, oh my god, oh, sorry, my bad, I need to, okay, there you go, and I'm going to say get all the types from button style, and button style is not a class anymore, so it's whatever is returned from recipe. So now go back to our component and I will import the type that I have just created, what's called bun variants, there you go, and then I'm going to add my new prop, and here we're going to say for my class name, now the bun side as I mentioned is not a simple string anymore, it's a function and you pass in your type prop here, and based on the prop that you're passing it will return the correct class that you need for your component. So there's one last thing that I need to do, is to add these props here, so I want to have outline, and then I want to have text, and the first one it has a default value which is fill. Now let's go back to our browser, and ta-da, we have three variants of the same button, Let's see if the theme works, and yes it does, and as easy as that, within a few minutes I have been able to create a button with three variations and two themes, and that's the power of vanilla extract.