[RFC] Base UI customization API change

[michaldudak]

Context

The current shape of the customization API (slots and slotProps) came to life after discussions within the team and with the community (#21453). We realized, however, that it has its challenges. First, it's not the most ergonomic option when styling with Tailwind CSS or similar libraries. The necessity to use a callback form of slotProps makes it too verbose:

<Select
  slotProps={{
    root: (ownerState) => { className: `bg-neutral-900 ${ownerState.open ? 'rounded-b-lg' : 'rounded-lg'}` },
    listbox: { className: '...' }
  }}
/>

Additionally, slots and slotProps do not have related types (if you set a slot to MyComponent, the corresponding slotProps won't be automatically typed as MyComponentProps). This was to reduce the work the TypeScript compiler must do when you write your code.

Proposal

Component per node

Considering these (and a few other) problems, we decided that in order to make Base UI more developer-friendly, we need to change the customization API.

To start with, we will adopt the "component-per-DOM node" pattern instead of slots/slotProps. This means that each subcomponent that currently is a slot, will be declared explicitly as a subcomponent.

For example, the Select could look roughly like this:

<Select>
  <Select.Trigger className="bg-neutral-900 ..." />
  <Select.Listbox className="...">
    <Option value={1}>One</Option>
  </Select.Listbox>
</Select>

(we're still fleshing out the details and designing the API of each component so details may change)

This is easier to read and reason about, as every component corresponds to a DOM node.
This approach is used by all the other major unstyled libraries, so migrating from them to Base UI will be easier.

Component replacement API

The component-per-node pattern replaces the slotProps, but we still need a way to customize the type of the component rendered in each slot. So far, we've been using the slots prop for this, but it doesn't make sense when each slot is represented by a subcomponent.

We evaluated several patterns:

• polymorphic components using the as / component prop, as in Material UI (<Button component="span" />)
• passing the replacement component as a child of the component (<Button asChild><span /></Button>
• passing the replacement component in a prop (<Button render={<span />}}
• context-aware primitives (<Select><Button/><Listbox /></Select>)
• render prop (<Button render={(props) => <span {...props} />} />)

After considering the pros and cons of each approach, we settled on render props.

<Button render={(props) => <span {...props} />} />

This is the most low-level API that could be used to create higher-level APIs in design systems if needed. It also requires to explicitly handle incoming props, which, while more verbose, is safer on the type level). Render props were also considered when we discussed the API in mui/material-ui#21453, but were discarded due to low readability when applied to multiple slots. Now, when we only have one "slot" per component, this is a viable option.

An additional benefit of render props is that they allow to render content depending on the internal state of the component (for example, a different icon in a checked and unchecked Switch)

Feedback

We understand that Base UI, while still unstable, is already used in many projects. Since slots were the primary means of customization, introducing the new API will break these projects.
We would like to know how we can make these changes as smooth for you as possible (while not introducing additional maintenance cost).
We are considering creating a codemod (though we're not sure if we'll be able to cover all the cases reliably with it), creating wrapper components exposing the old API, or documenting how you can create such wrappers on your own.

We are eager to learn what you think about these changes.

[pranav-growthx]

Would this also introduce changes in the Hooks API? I assume the answer would be a no since it does not inclued components and provide APIs to get props instead but I'd still like some clarification.

I have somehow lived under a rock and found about the Base UI completely by accident today and I am really interested in how it progresses

[michaldudak]

In some cases yes. We haven't designed them fully yet, so I'm not able to provide details, but I anticipate that some changes will be required (for example introducing new hooks for subcomponents).

[DurchblickerFabian]

For the Component replacement API: Is it planned to still be able to easily use simple component replacements without the render pattern?
I would imagine, while being really great for complex customizations, it gets pretty annoying for simple changes like just the component type, say: <Button render={(props) => <span {...props} />} /> vs. <Button render="span" /> or <Button render={motion.button} />. If I just want to pass in my props without modifications, it's pretty verbose in my opinion.

And I have a related question: when we take a custom component as an example - would I pass my custom props in the render function or is the "slot component" then correctly typed and I can pass my props there (like in Material UI)?

And how does the render pattern affect potential re-renders/performance? I imagine it's harder to optimize unnecessary re-renders especially since we are just passing in a function. Or would you recommend creating a callback for that?

[atomiks]

Ergonomic Replacement

We discussed a shortcut for render in which you pass the element itself:

<Root render={<MyRoot />} />

Which is an ergonomic shortcut for:

<Root render={(props) => <MyRoot {...props} />} />

This is still able to side-step polymorphic typing issues, but is not implemented. cc: @michaldudak @colmtuite

Performance

Most of the elements you render are likely to be cheap. Since the props are arbitrary, if you have an expensive component, you should wrap it like so and only pass the necessary memoizable props:

const Cheap = React.forwardRef(function Cheap(props, forwardedRef) {
  // Do cheap work in here, while passing a memoizable prop(s) to the expensive component
  // wrapped in `React.memo()`:
  return (
    <div ref={forwardedRef} {...props}>
      <Expensive memoizableProp={props.memoizableProp} />
    </div>
  );
});


<Root render={(props) => <Cheap {...props} />} />

[neaumusic]

Think of jsx as an object/instance; render as a function that returns an object instance. You'd likely be able to pass the functional component like render={Cheap} if you have no additional props to inject

[oliviertassinari]

The shorthands API looks really cool. I guess it would need to work with https://react.dev/reference/react/cloneElement, but I guess it's fine. It's similar to the asChild prop https://github.com/radix-ui/primitives/blob/b32a93318cdfce383c2eec095710d35ffbd33a1c/packages/react/slot/src/Slot.tsx#L37.
Having a logic that automatically merges props could maybe make sense:

<Root className="bar" render={<MyRoot className="foo" />} />

---

For the Component replacement API: Is it planned to still be able to easily use simple component replacements without the render pattern?

@DurchblickerFabian Do you mean as a developer building a design system with Base UI, or as a developer using a design system built on top of Base UI? In the latter, I would expect to be able to change the leaf component, e.g. from a <button> to a <a>. But I guess this would be achievable by either wrapping with styled() or adding class names directly, simply developers building a design system with Base UI should never use the render prop unless they expect their users to override the value.

when we take a custom component as an example - would I pass my custom props in the render function or is the "slot component" then correctly typed and I can pass my props there (like in Material UI)?

I think you would do:

<Root render={(props) => <MyRoot myCustomProp={true} {...props} />} />

And how does the render pattern affect potential re-renders/performance? I imagine it's harder to optimize unnecessary re-renders especially since we are just passing in a function. Or would you recommend creating a callback for that?

I don't see the performance aspect. The render function would be pretty transparent, see the proof of concept of how it would work under the hood: #157 (comment).

[yordis]

Before I say anything, yes, Composition over configuration until you justify that a configuration is granted due to the complexity of a given component.

I am not trying to make an argument in favor of Configuration over Composition; I just want to share my thoughts about the topic here.

Slot Props

The necessity to use a callback form of slotProps makes it too verbose:

That is why, in practice, the ADR that I wrote (https://github.com/straw-hat-team/adr/blob/master/src/adrs/1358452048/README.md), which you are familiar with, never talked about slotProps and only slots because although it is convenient, it quickly becomes messy. What I always disliked about slotProps is that it promotes configurations over creating components. It was an anti-pattern from the get-go, IMO.

Configuration vs. Composition

Again, without arguing in favor of configuration, let's analyze some other existing patterns because I think the most significant pain is the slotProps idea, not the slots itself.

For example, take shadui select component: https://github.com/shadcn-ui/taxonomy/blob/main/components/ui/select.tsx and Radix.

Notice that all the "unstyled" components are wrapped with the new classes, properties, and whatnot.

In the same way, if you removed the slotProps, you would be forced to create your components that receive previous classes and whatnot, promoting Components over callbacks and object configurations. They are the same, either configuration or Composition, for that particular concern, with no differences from my perspective. You would create a component that deals with given inputs, except that, in most cases, you wouldn't need to call a Primitive component yet, although you already swapped (well, Context-driven).

One caveat I also wrote in the ADR is that extra properties that weren't part of the internal control flow, leaning towards HoC, are sometimes needed to create the slots. However, that should be a rare case.

These "primitive" components should barely do the HoC because they are closer to the design system than business domain-specific data. Hence, they are genuinely as generic as they get, except for Graphics (CSS) and Semantics (HTML).

The real caveat is controlling the order, timing, and locations of the components you inject.

For this context, Slots vs. Composition is about "how you are doing the control flow." What most people do not realize from Radix is the massive complexity of everything to be based on "React Context" just because they gave up on the Control Flow.

Although the Radix-way composition feels more composable from the outside, that is only an illusion. The user must be careful regarding order, timing, and locations. And from the library author, it is just a matter of React Context everywhere!

What that means in practice is that Users will be taking some complexity and Library Authors dealing with every possible composition edge case out there, having to draw the line in a "given configuration" and usage (hah, we are back again to the same place), but just in a "composed" way.

If you dig a bit into it, you will find a massive complexity to give this illusion:

• https://github.com/radix-ui/primitives/blob/7b89539f5a5d955c28d8a905967c6e28197ae8a5/packages/react/collection/src/Collection.tsx#L123
• https://github.com/radix-ui/primitives/blob/7b89539f5a5d955c28d8a905967c6e28197ae8a5/packages/react/collection/src/Collection.tsx#L61

Doing things that are proven to be dangerous, such as worrying about the value of children and cloning children

• https://github.com/radix-ui/primitives/blob/784fa96dcecb66c2871c840b6bdbcf35b515ce6f/packages/react/slot/src/Slot.tsx#L14-L39

With a lot of complexity behind (and slow):

• https://github.com/radix-ui/primitives/blob/784fa96dcecb66c2871c840b6bdbcf35b515ce6f/packages/react/slot/src/Slot.tsx#L91-L122

Just read that Slot file itself...

But whatever they made it work, I think you may be asking for way too much headache as a library maintainer. The users may just need to move away from slotProps for the time being until slots itself is the actual problem.

That is my 2 cents based on my basic understanding of the situation. What I honestly believe is that React itself should come up with a better strategy around having Slots built-in!

[yordis]

Reflecting on the situation after talking to @oliviertassinari about it,

I would promote the usage of the Radix Slot Component (literally or trying to follow
@nihgwu https://github.com/nihgwu/create-slots or please take ownership of creating a RFC) and hopefully align the Mui, Radix, Headless, and React Aria ecosystem to optimize such components and patterns to a point where the React team would take ownership of providing a built-in capability to have Slots.

The browser itself already has this https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot, and many other ecosystems (like Vue) are given to have the Slot pattern.

[yordis]

radix-ui/primitives#3165

[oliviertassinari]

the API in mui/material-ui#21453, but were discarded due to low readability when applied to multiple slots. Now, when we only have one "slot" per component, this is a viable option.

@michaldudak Right, I think for me the issue with the render pattern, to make it work you need to do something like this:

// Base UI
function BaseSlider(props) {
  const { render, ...other } = props;
  return render({
    ...other,
    children: <input type="range" />,
  });
}

// Material UI
function Slider() {
  const StyledRoot = (props) => (
    <span {...props} style={{ background: "red" }} />
  );
  return <BaseSlider render={(props) => <StyledRoot {...props} />} />;
}

// Actual user
export default function App() {
  return (
    <div>
      <Slider />
    </div>
  );
}

https://codesandbox.io/p/sandbox/base-ui-render-forked-hph4zp?file=%2Fsrc%2FApp.js%3A13%2C54

But then:

1. developers can create new components in their render function. I guess, it's a sign that it's more flexible, so people can shoot themselves in the foot. Probably OK.
2. Developers can try to use hooks in render functions and have surprising behaviors. [data grid] The renderCell property can't receive a component with hooks mui-x#4937 (comment)
3. for the developers who would read the source, it feels weird. With this pattern, I imagine that we can't really use JSX. I would read the source of Material UI a LOT when I was using it for a real project to customize it, to be honest, it was hard not to read the source, to truly use Material UI. Now, I think that the problem is mostly solved because Base UI is a separate package now. So I would continue to spend my time in the source of Material UI, and get clear sources to customize the styles, especially with the move to one React component for one DOM node.

[michaldudak]

developers can create new components in their render function. I guess, it's a sign that it's more flexible, so people can shoot themselves in the foot. Probably OK.

A render function is not a component definition. The function is called, whereas a component would be passed to React for rendering. This is a huge difference.

it was hard not to read the source, to truly use Material UI.

We should make the docs good enough not to require developers to dive into the source. Browsing the Material UI source to learn how to implement a real-life design system is OK, though, IMO.

[michaldudak]

Also, we provide the "short" render prop variant:

<BaseSlider render={<StyledRoot />} />;

[oliviertassinari]

Right, I guess it's ok. It was still possible before.

So it's more the opposite confusion, the one we saw in the DataGrid. People trying to use hooks in the render prop and not always having consistent behaviors 😁. mui/mui-x#4937 (comment)

[nihgwu]

Interesting, so you eventually chose the same approach AriaKit https://ariakit.org/guide/composition, and I like it
I just realised it has been two years since I created React Slots RFC and create-slots, I‘m very pessimistic on the future, React 19 is the best gift for ui library authors, and Slots is the last missing piece
The most ergonomic approach is RAC's style, I had the same idea about 3 years ago, but given the context of RSC, all those context base solution don't seem so plausible, and I'm leaning to render style more, as it just requires React basics to implement it while the other solutions are full of hidden black magics

[yordis]

I‘m very pessimistic about the future,
Slots is the last missing piece

Please do not be! We need Slots built-in and somebody to take ownership of documenting all the pain across the ecosystem!