If you've ever used a native `<select>` and `<option>` in HTML, you've already
experienced the power of **compound components**—even if you didn't know the
name.

But what if you could bring that same flexibility and declarative power to your
own React components? That's what the Compound Components pattern is all about.

## What and Why: Compound Components in React

Compound components are a set of components that work together to form a
complete UI, implicitly sharing state and behavior. Think of them as a family:
each member has a role, but they all work together seamlessly.

The classic example is HTML's select:

```html
<select>
	<option value="1">Option 1</option>
	<option value="2">Option 2</option>
</select>
```

The `<select>` manages the state, and the `<option>`s are just configuration.
You don't have to wire them up manually—they just work.

You _could_ build a custom select like this:

```tsx
<CustomSelect
	options={[
		{ value: '1', display: 'Option 1' },
		{ value: '2', display: 'Option 2' },
	]}
/>
```

But what if you want to add custom attributes to an option, or change how it's
displayed when selected? You'd have to keep adding more props and configuration,
making your API more complex and less flexible.

Compound components let you keep your API simple and declarative:

```tsx
<CustomSelect>
	<CustomOption value="1">Option 1</CustomOption>
	<CustomOption value="2">Option 2</CustomOption>
</CustomSelect>
```

Now, you can pass _anything_ as children, and each option can be as flexible as
you need.

The parent component (like `<CustomSelect>`) manages the shared state and passes
it down to its children using React's context API. The children (like
`<CustomOption>`) consume that context and interact with the parent as needed.

This pattern lets you build components that are:

- **Flexible:** Users can compose your components however they want.
- **Declarative:** The structure of the UI matches the structure of the code.
- **Extensible:** Add new features without breaking existing APIs.

## Real-World Impact & When to Use

This isn't just a theoretical pattern. It's used in some of the most popular UI
libraries, like
[Radix UI Tabs](https://www.radix-ui.com/primitives/docs/components/tabs) and
[Radix UI Accordion](https://www.radix-ui.com/primitives/docs/components/accordion).
In fact, most of [Radix UI](https://www.radix-ui.com/primitives) is built on
this pattern.

Reach for compound components when:

- You want to give users maximum flexibility in composing your UI.
- You want to avoid prop explosion and keep your API clean.
- You want your components to "just work" together, like native HTML elements.

Want to master patterns like this—and many more?
[EpicReact.dev](https://epicreact.dev) is packed with hands-on workshops,
real-world examples, and deep dives into the patterns that make React apps
scalable and maintainable. Whether you're a beginner or a seasoned pro, you'll
find something to level up your React skills.


Build flexible, declarative UIs like native HTML with Compound Components—a powerful React pattern you’ll master at EpicReact.dev.

Compound Components: Truly Flexible React APIs

React server components have been stirring up the developer community, and I've noticed a mix of excitement and concern. Some folks are uneasy about the blurred lines between server and client, and the implementation challenges, especially with Next.js. But despite these bumps in the road, I want to tell you why I continue to be optimistic about the future of React Server Components.

## Why React Server Components Matter

For decades, we've grappled with integrating backend logic and front-end interactivity in a seamless way. React server components step in as a remarkable solution to this age-old problem. They allow us to compose server and client code without the usual hassle of switching between models.

The network is what makes web development so tough for the majority of web applications. Remix and other frameworks have done a great job of bridging the network chasm and I've really enjoyed using Remix for the last few years. It completely changed what it felt like to build web apps for me and enabled me to handle more and more use cases on my own with a better user experience.

But bridging the network chasm isn't enough. Ryan Florence's talk ["Mind the Gap"](https://www.youtube.com/watch?v=zqhE-CepH2g) at Big Sky Dev Con last month was a real eye-opener. If you haven't seen it yet, do yourself a favor and [watch it](https://www.youtube.com/watch?v=zqhE-CepH2g). He perfectly illustrates the power of React server components in not only bridging the gap between the backend and the frontend, but **making the network completely disappear**.

## Addressing the Pain Points

It's true that React server components introduce new challenges. These fresh pain points can seem daunting because we're not used to them. But let's not forget that all innovations in software come with their own set of hurdles. What's important to remember is that these pain points won't always be there. With any new technology, this is as tough as it gets, and it can only improve from here.

I have high hopes for Remix and its potential to implement React server components in a way that will alleviate many of the current pain points. The team behind Remix is poised to deliver an exceptional developer and user experience (as they have consistently done over the last decade of development with React).

Yes, there are complexities, especially for framework authors grappling with React server components. It's a tough time to be in their shoes, with all the abstractions that need to be figured out. But for the benefit of framework users, the effort is worthwhile. The goal is clear: to build better user experiences with an amazing developer experience. I'm confident the juice is worth the squeeze.

## The Promise of React Server Components

What stands out with React server components is their ability to seamlessly compose interactions between the client and the server. This is what Ryan described as the elimination of the "network chasm" in both directions. I'm confident that React server components are the future, and we'll look back at these times as the necessary growing pains that led to better solutions.

### Looking Ahead with Optimism

Folks who are using React Server Components right now (most of them are working in Next.js apps) are in the midst of uncertainty, dealing with boilerplate and annoyances. But once we develop the right level of abstractions, we'll be able to create user experiences that are not only better but also easier to build.

I'm super bullish on what Remix is doing. They're on track to do an amazing job, and I can't wait to see it unfold. So, to those of you who are worried about React server components and their impact on the React developer's future, I urge you to share my optimism. Things are only going to get better from here.

## What to do now?

Personally, I think it's worthwhile to learn about React Server Components. There are framework implementations of RSCs currently in frameworks that don't match my sensibilities so I'm not actively using them yet. For now, I'm sticking with Remix/React Router as a phenomenal way to build excellent user experiences on the Web. There are shortcomings with Remix for now for sure, but those will be largely solved by RSCs.

If you've not watched Ryan's other talk at React Conf titled ["Vanilla React"](https://www.youtube.com/live/T8TZQ6k4SLE?si=9-31tLaqqIarAO3K&t=5533), then you should definitely watch that to see what the RSC experience with React Router v7 will be like (it'll be amazing). So stick with Remix/React Router and you'll be well situated to take advantage of RSCs when they're ready. And it'll enable you to build better experiences faster.

Have a nice day, and stay optimistic about the future of web development!

React Server Components are going to improve the way we build web applications in a huge way... Once we nail the abstractions...

React Server Components: The Future of UI

Let's analyze this React tree structure:

```tsx
<App>
	<ShipSearch />
	<ShipDetails />
</App>
```

Let's assume that `App` renders the `ShipSearch` and `ShipDetails` components,
passing props as needed.

`ShipSearch` is a server component which takes a `search` and uses that to
perform a database query:

```ts
async function ShipSearch({ search }) {
	const shipResults = await searchShips({ search })
	// ... render stuff
}
```

The `ShipDetails` component is also a server component which takes a `shipId`
and uses that to perform a database query:

```ts
async function ShipDetails({ shipId }) {
	const ship = await getShip({ shipId })
	// ... render stuff
}
```

Because these are sibling components, both queries will run at the same time.

```
searchShips query  ---->  searchShips result
getShip query      ---->  getShip result
```

## Server Waterfalls

That's all fine. But let's say the `App` component needs to resolve a logged in
user:

```ts
async function App() {
	const user = await getLoggedInUser()
	// ... render stuff
}
```

Uh oh, now we have a waterfall:

```
getLoggedInUser query ---->  getLoggedInUser result
                             searchShips query      ---->  searchShips result
                             getShip query          ---->  getShip result
```

The issue here is now `App` is waiting for `getLoggedInUser` to resolve before
it can render anything. This means both `searchShips` and `getShip` won't be
executed until _after_ `getLoggedInUser` resolves, even though those don't
directly depend on the user.

This is a problem generally for React Suspense as well and I dive deep into that
in the
[React Suspense workshop exercise 6](https://suspense.epicreact.dev/exercise/06).

There are a few ways to think about this problem:

Maybe it's not a problem if `getLoggedInUser` is fast 🤷‍♂️ But that's not always a
sure thing, and even if it's fast today doesn't mean someone won't add something
else that will be slow tomorrow. Still, it's always good to think about how bad
ignoring the problem would actually be since there could be bigger fish to fry.

Alternatively, we can lift `searchShips` and `getShip` into `App` and pass the
results down to `ShipSearch` and `ShipDetails`. Then we could use `Promise.all`
to make sure they run concurrently. But passing props can get annoying pretty
fast. We can use a library like
[`@epic-web/cachified`](https://github.com/epicweb-dev/cachified) to dedupe the
queries and then `App` simply kicks off the query earlier which would at least
be better.

Unfortunately, another issue though is this can get unweildy pretty fast,
especially if there's logic around which queries should run based on other
props. You'd have to move all that logic until your entire app lives in `App`
😱.

The next solution I can come up with is to use or build a compiler which can
find all queries and preload them automatically. This is what Relay is. There
are quite a few things I don't like about this approach though:

1. If you have logic around which queries should run based on other props, this
   approach doesn't work.
2. It adds a lot of complexity to your build process.
3. When you're working in product code, it's not obvious what's happening.

So I guess what I'm saying is I don't like any of these solutions. But I'd like
to reframe the problem with more context.

## The status quo

Let's say we live in a world where we don't have RSCs or Suspense. You're just
building an app with components that fetch data and render stuff.

In that world you've got three options:

1. Group together (colocate) your queries with the components that need them.
2. Lift all your queries into a single component and pass the results down.
3. Use a compiler to find all your queries and preload them automatically.

Sound familiar? It's exactly the same problem we've always had with components
and data. There's always been this tension between colocating and passing down
data (prop drilling).

One of the nice things about Remix is that it gives you a fourth option:

4. Decouple your data fetching from your components.

This allows Remix to load data as soon as the request comes in regardless of
whether the component has rendered.

This is what I've been doing for years and it's been awesome.

## So, why RSCs?

This blog post isn't really about why I think RSCs are awesome. You can read
[React Server Components: The Future of UI](https://www.epicreact.dev/react-server-components-the-future-of-ui)
for that. Just know that composition at route boundaries is not as good as
composition at component boundaries and I want React-level composition badly.

What I want to do is show how RSCs fit into the same tension between colocating
and prop drilling that we've always had with components and data. There's no new
problems here.

But what I find interesting is how a server-side waterfall is probably better
than a client-side waterfall primarily because you get to control the network.
The connection between your server rendering server and your database is
probably stronger, faster, more reliable, and closer. Or maybe it's not, but the
point is _you_ are in control there and can make improvements to that if it's
important to you. You also have more fine-grained control over caching (requests
from separate clients can share a cache for common data).

When you have a client-side waterfall, you're dealing with the user's device and
their network connection which may be great or may be terrible but you
definitely have no control over.

So shifting this problem from the client to the server sounds like a net gain
for many scenarios.

## Conclusion

The "waterfall" problem of RSCs is not a new problem. It's the same tension
between colocating and prop drilling that we've always had with components and
data. Maybe there's a new solution we can look forward to in the future. I
welcome ideas (preferrably something that doesn't require a special compiler)!
Until then, I'm actually pretty happy with just making things fast enough that the
problem isn't a problem.


Understanding server-side waterfalls with RSCs and client-side waterfalls we're familiar with and why server-side waterfalls are probably better.

The Big "Server Waterfall Problem" with RSCs

If you've used React for a while, you've probably run into this before:

```
index.js:1 Warning: Each child in a list should have a unique "key" prop.

Check the render method of `App`. See https://reactjs.org/link/warning-keys for more information.
    at li
    at App (http://localhost:3000/static/js/30.chunk.js:48:75)
```

You probably know the solution as well. Here's the rule:

**Whenever you're rendering an array of React elements, each one must have a unique `key` prop.**

Here's the simplest way to reproduce this problem:

```tsx
const items = [
  {id: 'apple', value: '🍎 apple'},
  {id: 'orange', value: '🍊 orange'},
  {id: 'grape', value: '🍇 grape'},
  {id: 'pear', value: '🍐 pear'},
]

function App() {
  return (
    <ul>
      {items.map((item) => (
        <li>{item.value}</li>
      ))}
    </ul>
  )
}
```

And the solution is pretty simple:

```diff
-         <li>{item.value}</li>
+         <li key={item.id}>{item.value}</li>
```

But like... Why? React doesn't seem to have a problem if I were to write it like this:

```tsx
function App() {
  return (
    <ul>
      <li>🍎 apple</li>
      <li>🍊 orange</li>
      <li>🍇 grape</li>
      <li>🍐 pear</li>
    </ul>
  )
}
```

It's only a problem if I try to pass the elements as an array. So yeah, why does React have such a big problem with arrays anyway?

First, if you want to understand what problems can happen without the `key` prop (and cool things you can do with it), read [Understanding React's key prop](https://kentcdodds.com/blog/understanding-reacts-key-prop). In this post, I just want to explain why React can't just magically make things work without a `key` prop.

I want you to pretend you're React and I'm a React developer building an application. I'm writing a function component called `App`. You don't get to see my implementation, all you get is the function which you can pass arguments to and receive a return value from.

So let's say I give you that function and tell you to render that to the page. So you call `App` and you get the following React elements back ([learn more about React elements](https://kentcdodds.com/blog/what-is-jsx)):

```js
const element = {
  type: 'ul',
  key: null,
  props: {
    children: [
      {type: 'li', key: null, props: {children: '🍎 apple'}},
      {type: 'li', key: null, props: {children: '🍊 orange'}},
      {type: 'li', key: null, props: {children: '🍇 grape'}},
      {type: 'li', key: null, props: {children: '🍐 pear'}},
    ],
  },
}
```

Ok, first, you're going to warn right? Because the `key` is `null` for all of those children. 😉 But really, it's fine. You're React and you know how to take these elements and render them to the page. So you render the `ul` and `li`s to the page. All's good.

Ok, so now my `App` calls a state updater function and so you know you need to re-render. So you call `App` again and this time you get some new React elements:

```javascript
const element = {
  type: 'ul',
  key: null,
  props: {
    children: [
      {type: 'li', key: null, props: {children: '🍎 apple'}},
      {type: 'li', key: null, props: {children: '🍊 orange'}},
      {type: 'li', key: null, props: {children: '🍐 pear'}},
    ],
  },
}
```

Ok, so you do a quick and easy diff here:

```diff
-      {type: 'li', key: null, props: {children: '🍇 grape'}},
```

Oh, cool, so you can just remove the `li` from the page right? Yeah, go ahead and just unmount it. Sure, do that. Easy-peasy.

Ooh! I need another state update, so you get the next set of React elements:

```javascript
const element = {
  type: 'ul',
  key: null,
  props: {
    children: [
      {type: 'li', key: null, props: {children: '🍊 apple'}},
      {type: 'li', key: null, props: {children: '🍐 pear'}},
    ],
  },
}
```

Now do another diff:

```diff
-       {type: 'li', key: null, props: {children: '🍎 apple'}},
-       {type: 'li', key: null, props: {children: '🍊 orange'}},
+       {type: 'li', key: null, props: {children: '🍊 apple'}},
```

Hmm... Ok, so now... Should remove the `🍎 apple` and `🍊 orange` `li`s and create a new one with `🍊 apple`? How certain are you that this is what I meant to do? Maybe what I actually want is to remove the `🍎 apple` and rename `🍊 orange` to `🍊 apple`... Or maybe I want to remove the `🍊 orange` and rename `🍎 apple` to `🍊 apple`. Or maybe I want to remove `🍐 pear`, then rename `🍊 orange` to `🍐 pear`, and then rename `🍎 apple` to `🍊 apple`...

Now you're thinking "Ugh. What the heck? Mr. Dodds. Give me a break."

So, as React, you do your best guess: You pretend the `key` is the `index`. I mean, you gotta do something right? This is what React actually does.

Interestingly, this means that rather than just unmounting the `🍇 grape` `li` on that first state update, you actually unmounted `🍐 pear` and updated `🍇 grape` to say `🍐 pear` 😂. But in a real app, this is no laughing matter. Unmounting and mounting components has implications on the state and side-effects of a component (which I describe in more detail in the aforementioned blog post).

And that also means with this last state update, you unmounted `🍐 pear` again and updated `🍎 apple` to be `🍊 apple` and `🍊 orange` got updated to say `🍐 pear`. What a disaster!

This is definitely not the most optimal, but what are you gonna do? You have no idea what I meant with that element change!

(By the way, I used [this code](https://codesandbox.io/s/romantic-kalam-mliwb?file=/src/index.js) to validate what was going on, if you want to poke around).

## In walks the `key` prop...

Phew... Wouldn't it be nice if I had given you some way to track the React elements from one render to the next so your diff could be more informative. That way you'd know my intent much better right?

Yeah, let's try that last one, only with `key`s this time:

```javascript
const element = {
  type: 'ul',
  key: null,
  props: {
    children: [
      {type: 'li', key: 'apple', props: {children: '🍎 apple'}},
      {type: 'li', key: 'orange', props: {children: '🍊 orange'}},
      {type: 'li', key: 'pear', props: {children: '🍐 pear'}},
    ],
  },
}
```

Ok, nice, so now here comes the update for you:

```javascript
const element = {
  type: 'ul',
  key: null,
  props: {
    children: [
      {type: 'li', key: 'apple', props: {children: '🍊 apple'}},
      {type: 'li', key: 'pear', props: {children: '🍐 pear'}},
    ],
  },
}
```

Ha! Now you know exactly what to do! You can now do a much more granular diff. First you notice that the element with the `key` of `'orange'` is gone, so you know you can remove that from the page. And the element with the `key` of `'apple'` has new `children` so you can simply update it and move on with life without worrying about whether you're doing the right thing.

Oh, and for our very first change when we removed the grape `li`, you can correctly just remove that one now too.

## Conclusion

Now that you've put yourself in React's shoes, hopefully you understand why React can't just magically know what you're doing with your elements and why you need to provide a `key` prop. Frankly, this is a limitation in React. It would be nice to not have this limitation, but not at the expense of React's simplicity (which is [what I love most about React](https://epicreact.dev/why-i-love-react)). I hope this article helped you get an solid understanding of why the `key` prop is needed when rendering arrays.

I'll leave you with one more thought... With your understanding of the `key` prop now, can you think of situations where you could use a `key` prop _outside_ an array? The `key` prop has less to do with arrays, and more to do with controlling when a component is reused or disposed of and created anew. Give that some thought 😄

Why can't React just magically know what to do without a key?

Why React needs a key prop

I've been riding the CSS-in-JS train for years (I was even a significant contributor to the "movement"). It's awesome. I've never been so productive working with CSS than when I added the power of JavaScript to it.

I'm still a fan of CSS-in-JS, and in recent years, the CSS spec has evolved and improved a lot and modern browsers have too (unfortunately, Internet Explorer is NOT a modern browser in this or any context). Often I'd use a `ThemeProvider` (like those found in emotion), but turns out there aren't a whole lot of advantages to that kind of component for many use cases and there are several disadvantages.

Let's look at a simple example of "Dark Mode" and compare differences in API (developer experience) and performance (user experience). We'll keep the example simple, and in both the before/after, we'll be using emotion's `styled` utility. Keep in mind that with the `ThemeProvider` you can consume the values using the `useTheme` hook, with a styled component, or with the `css` prop. With CSS Variables, you can get the values in your CSS with `var(--css-variable-name)` and in your JavaScript using `getComputedStyle(element).getPropertyValue('--css-variable-name')` (which you really don't need to do...)

Ok, let's look at some code. Here's an approach to using emotion's `ThemeProvider`:

```javascript
import * as React from 'react'
import styled from '@emotion/styled'
import {ThemeProvider} from 'emotion-theming'

const themes = {
  light: {
    colors: {
      primary: 'deeppink',
      background: 'white',
    },
  },
  dark: {
    colors: {
      primary: 'lightpink',
      background: 'black',
    },
  },
}

const PrimaryText = styled.div(({theme}) => ({
  padding: 20,
  color: theme.colors.primary,
  backgroundColor: theme.colors.background,
}))

function ThemeToggler({theme, onClick}) {
  const nextTheme = theme === 'light' ? 'dark' : 'light'

  return (
    <button onClick={() => onClick(nextTheme)}>
      Change to {nextTheme} mode
    </button>
  )
}

function App() {
  const [theme, setTheme] = React.useState('light')
  return (
    <ThemeProvider theme={themes[theme]}>
      <PrimaryText>This text is the primary color</PrimaryText>
      <ThemeToggler
        theme={theme}
        onClick={(nextTheme) => setTheme(nextTheme)}
      />
    </ThemeProvider>
  )
}

export default App
```

What's cool about this is it's "just JavaScript" so you get all the benefits of variables etc. But we're not really doing all that much with this other than passing it around through the ThemeProvider. (To be clear, the way the ThemeProvider works is it uses React's Context API to make the theme accessible to all emotion components without having to pass props all over the place).

Let's compare this with the CSS Variables approach. But before we get to that, I need to mention that there's no "ThemeProvider" for this. Instead, we define the variables in regular CSS that will get applied based on a `data` attribute we apply to the `body`. So here's that css file:

```css
body[data-theme='light'] {
  --colors-primary: deeppink;
  --colors-background: white;
}

body[data-theme='dark'] {
  --colors-primary: lightpink;
  --colors-background: black;
}
```

Alright, so with that, here's the implementation of the exact same UI:

```javascript
import * as React from 'react'
import './css-vars.css'
import styled from '@emotion/styled'

const PrimaryText = styled.div({
  padding: 20,
  color: 'var(--colors-primary)',
  backgroundColor: 'var(--colors-background)',
})

function ThemeToggler() {
  const [theme, setTheme] = React.useState('light')
  const nextTheme = theme === 'light' ? 'dark' : 'light'

  React.useEffect(() => {
    document.body.dataset.theme = theme
  }, [theme])

  return (
    <button onClick={() => setTheme(nextTheme)}>
      Change to {nextTheme} mode
    </button>
  )
}

function App() {
  return (
    <div>
      <PrimaryText>This text is the primary color</PrimaryText>
      <ThemeToggler />
    </div>
  )
}

export default App
```

Let's first compare what it's like to _use_ these values:

```javascript
// ThemeProvider:
const PrimaryText = styled.div(({theme}) => ({
  padding: 20,
  color: theme.colors.primary,
  backgroundColor: theme.colors.background,
}))

// CSS Variables:
const PrimaryText = styled.div({
  padding: 20,
  color: 'var(--colors-primary)',
  backgroundColor: 'var(--colors-background)',
})
```

There's not really much of a difference from a DX (development experience) standpoint here. One point for the CSS Variables approach is not having to create a function that accepts the theme and returning styles (and no need to even learn about that API).

One point for the `ThemeProvider` approach is if you're using TypeScript you could get type safety on your theme... But ummm... [Check this out](https://twitter.com/chochihim/status/1324182272304537600):

```javascript
// src/theme.js
const theme = {
  colors: {
    primary: 'var(--colors-primary)',
    background: 'var(--colors-background)',
  },
}
export {theme}

// anywhere-else.js
import {theme} from 'theme'

const PrimaryText = styled.div({
  padding: 20,
  color: theme.colors.primary,
  backgroundColor: theme.colors.background,
})
```

BOOM. Static typing-friendly.

Either way, that's really the only significant DX difference. Let's consider the UX (user experience) difference. Why don't you play around with it:

<iframe   src="https://codesandbox.io/embed/df90h?view=Editor+%2B+Preview&module=%2Fsrc%2Findex.js"   style={{     width: '100%',     height: '500px',     border: 0,     borderRadius: '5px',     overflow: 'hidden',   }}   title="CSS Variables vs ThemeProvider"   allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts" ></iframe>

You'll notice there's not really any observable UX difference, and there's not for this simple example. But why don't you try this with me:

1. pop open the React DevTools Profiler 2. Start a profiling session (click the little circle) 3. Click the toggle button for each 4. Stop the profiling session 5. Compare the two commits

Here's what I see:

**ThemeProvider:**

![Profiling session showing everything rendered](/articles-images/css-variables/theme-provider.png)

**CSS Variables:**

![Profiling session showing only one component rendered](/articles-images/css-variables/css-vars.png)

I don't want you to get hung up on the number of milliseconds to rerender. This isn't a controlled benchmark (we're in React's dev mode for one thing). The thing I want you to consider is how many components needed to re-render for this change. Let's consider the `ThemeProvider` approach first. The main reason for this is the way we've structured our state ([we could restructure things](https://kentcdodds.com/blog/optimize-react-re-renders) and improve it a little bit). But even if we restructured things, when the theme changes, _every_ emotion component needs to be re-rendered to account for the theme change.

Turning to the CSS Variables approach, you'll notice the only component that re-rendered was our `ThemeToggler` component responsible for updating the `body`. And yet the user experience works perfectly! This is the magic behind CSS variables. With the `ThemeProvider` approach, we have to update the styles of every component, and then the browser paints those updates. But with the CSS Variables approach, we update the styles to a single component (the `body`) and then the browser paints those updates. The browser paint should theoretically take the same amount of work on the part of the browser, so the only difference is how much work we're making the browser do to have React re-render all our components and get emotion to update the styles of every component.

This _can_ have negative performance implications as your app grows. Considering the DX isn't objectively better or worse either way, but the UX is quite possibly better with CSS Variables, I feel comfortable recommending CSS Variables over using Context to share a theme like this.

Oh, and consider also that CSS Variables are part of the browser spec and the ThemeProvider isn't. That's another solid point for CSS Variables 😉

This is one standard I'd suggest you embrace.

One last piece of nuance here. What if you not only want to change styles but _also_ want to change component implementations based on the theme? In this case... [YOU CAN DO BOTH](https://twitter.com/sebmarkbage/status/1324097255557767173)! The benefit of doing this is the only components that need to consume the context value are those that need to render differently based on the theme (which is likely a small subset). Most components can use the css variables for styling purposes only, so you'll still get the aforementioned benefits. If you don't _need_ components to render differently based on the theme then I wouldn't bother with this, but if you do, then it's pretty simple to do. There are several ways to accomplish this, I've done one implementation in [the codesandbox](https://codesandbox.io/s/css-variables-vs-themeprovider-df90h?file=/src/both/index.js). Enjoy exploring that.

CSS variables (custom properties) are awesome. Give them a look. Good luck!

How and why you should use CSS variables (custom properties) for theming instead of React context.

Compound Components: Truly Flexible React APIs

What and Why: Compound Components in React

Real-World Impact & When to Use

Get my free 7-part email course on React!

More Articles

React Server Components: The Future of UI

The Big "Server Waterfall Problem" with RSCs

Why React needs a key prop

Use CSS Variables instead of React Context