Polymorphic React Components for Both the Client and the Server

Hi, my name is Kirill and I have a little obsession with UI components. In fact, I'm doing this full-time at Progress, building the next generation of the CanDo React library. During my free time, I love exploring the design system space, and currently I'm building a design system framework which I'm calling BackerUI.

But enough about me. Let's talk React, and more specifically, the new edition of React 19, Server Components, which if you ask me, should have been called simply React Components. But anyway, when Server Components initially came out, they promised a smaller bundle size, better performance, and improved data fetching, which led me to believe that I should rewrite all my user interface to use Server Components. This turned out to be a really bad idea, even Lee Robinson had to tweet that client components are actually fine. At some point, I even had a server button. It looked exactly like a regular button, but it was mostly useless because it didn't have a click event. I ended up keeping my client components.

But along the way, I realized I had a client and a server variant of some of my components. On paper, a data table could greatly benefit from being a server component, but I still needed to provide interactivity for implementing more dynamic dashboards or e-commerce shopping carts. Today, I want to show you how I built what I call a polymorphic data table, a single component which can be used to put on the client and as a server component. But before that, let's make sure that we are all visualizing the same thing when we think data table. A data table usually displays tabular data. It can have a header, a body, multiple rows with cells inside which shows formatted data. Cool. Now we're on the same page. But I still ended up with two really similar looking UI components.

One server data table, which sent only HTML to the client, had access to my file system and even a database instance. And one client component, which was interactive. I could edit, sort, and filter the data without a trip back to the server and had access to the browser APIs and the DOM. Usually, if I was building my personal blog posts, it would be perfectly fine to have two similar looking UI components with different purposes. However, if you are like me and are building a reusable UI library, being an open source one or something for other teams in your organization, there are a couple of things you should consider. First is code duplication. You probably do not want to maintain two separate code bases, which do almost the same thing, rendering a couple of rows with cells inside. Second is how consumers of your library would further modify to meet their requirements. A lot of applications have individual needs which may require a mix of server and client code, customizing all parts of your component along the way. And lastly, requirements change. They always do.

Someone starting with the server component should be able to easily add interactivity later on without having to replace the whole component. A specific pattern has emerged to help us mix and match server and client components. You have probably seen this diagram, which we refer to when speaking about the composition pattern.

Everything looks good on paper, but it is often applied on an application level. When we zoom into the component level, UI libraries are usually going full client mode, which diminishes the benefits of using server components. Let's explore for a bit how the rendering tree of a data table would look like and see if we can apply the composition pattern there. If you have tried implementing a data table before, you would quickly come to the realization that you need client code almost anywhere in the tree. Being for accessibility or adding a simple row selection feature, most of the rendering tree would end up not being able to use server components at all.

This is problematic because consumers of your data table might still want to keep some of the rendering on the server. But from the rules of server components, we know that while server components can render client components, the opposite is not true. There is, however, a way to achieve this by passing everything through the children pod prop, but we are going to explore this in a minute. Now, back to our data table.

My favorite example is an API table which shows documentation for UI component or software of any kind. To make everything readable and beautiful, we are sometimes rendering markdown with code blocks inside, but markdown libraries are chunky and often end up in your client bundle. It's even worse if you want to syntax highlight thing for the code blocks.

What I want to be able to do is render a markdown cell without affecting the client code. I know there are some other ways to achieve this, but the most straightforward implementation for me would be something like this as passing a specialized cell which does all the job without negatively affecting the client bundle.

Now, let's deep dive into how we can achieve this by using a pattern which I have called a polymorphic component, a component which can be can render any of its nodes both on the client or the server. To achieve this, we must simply follow some basic rules. First, components should not be rendering their own children. And second, their client logic should be separated.

With those two simple rules, we would be able to render custom components across the whole component tree without breaking client functionality and still be able to morph into a fully client component for application which does not support or require server components. If we apply those rules correctly, the rendering tree should look something like this. Each node in the tree is agnostic, meaning it could be rendered both as a client or as a server component. Additionally, the client parts of a component are extracted into a client shell where they are not affecting the rendering of the original component.

Now let's go over the first rule of not being responsible for your own children in the context of UI components of course. If previously our root data table components was directly rendering the role, we are now introducing an intermediate component. I still haven't found a good name for those, but for now I'm calling them view components. The idea of a view component is to assemble the actual slot which can be customized, in our case the role, and prepare its children so that if the role needs to be either a client or a server component, its children, the cells, would not be affected by this decision, allowing them to be anything according to the application requirements.

Referring back to our use case with the markdown cell, the rendering pattern would allow us to render a server component in a leaf regardless of any other customization which we have made up in the tree. Now to our second rule. Eventually, you or your product manager would want to add a simple role selection feature and wouldn't care much about the performance implication if we bring the whole component to the client.

When I was first playing with server components, I thought that I could simply add anything from React to a component and it would work on the server instead of the client. But if you try to add the state to a component, which might be rendered on the server, like our agnostic parts of the data table, you would quickly end up with an error. The same goes to attaching DOM events, because how else would you know how to change the state? So, what we are seeing on the screen now does not work.

In order to make it work, we must extract all client logic into a separate component. Again, the best name I have come up with is adding a client at the end of the component's name. This allows us to work around the rendering of the component without affecting the tree directly and only providing the client context. This allows us to consume this context from the client's part of our other components. Again, only adding client-specific logic.

In our use case, that would be the role's client part, which must only add a click event and append a class name if the client state indicates that the role is selected. Zooming out to see the full picture, our port of mobile components look something like this, rendering from left to right and its client logic being extracted into a separate component with the use client directive.

Now, let's try to guess what happens if we use this component in a regular client application, for example, a Create React app or a Vite application. The component is not working correctly, since its agnostic parts are morphing into client components. Our components will still not work, but that's up to the frameworks underneath, not our component.

However, if we consume our component in a React server component environment on the right, like Next.js or a Wacom application, we could expect that our agnostic component to morph into server ones, leaving their JavaScript on the server and only sending or streaming, if you prefer, the HTML which they have produced. The client parts of our component is shipped in a separate bundle as we have separated it from the component itself.

With this, we conclude our journey of building a single polymorphic component which can be used as client component or as a server component or anything in between, actually, with minimal bundle size, interactivity, and access to both server and client APIs from its corresponding parts. Thanks for watching. If you have enjoyed this talk, you can follow me up on Twitter or X, if you prefer. If you would like to check my work, I'm currently building polymorphic components for Gendo React, and also feel free to check out my open-source design system framework, Baka.UI. Bye!