RFC: Slots

[nihgwu]

In this RFC, we propose a way to support Slots pattern in React

View formatted RFC

Here is a demo how it would work I implemented with react-call-return in 10 lines

[tom-sherman]

I'm very interested in this proposal, being able to build your own node tree and have it managed by react is very powerful.

The string-name based API makes this hard to impossible to statically type. This is something the context API gets right but I feel is missing in this proposal.

Do you have any thoughts on this? Maybe a createContext like API is better?

const{Host, Slot}=createSlot()

[nihgwu]

@tom-sherman for typings, you will have to do const Slot = createSlot<Props>(), in my own package it's automatically inferred, works the best with TS, but here I want to make it more generic and lightweight, so you will have to provide types manually, and it's just a one-time work, but you remind me an idea to improve the api, that we don't need string based slot name at all, tag type already does the job, will update soon.

Regarding HostSlot pair, I don't think it will help improving typings as we will have multiple slots while each one accept different props, like LabelSlot<LabelProps> and InputSlot<InputProps>

[tom-sherman]

The issue with the string-based API was that there is no easy way to say that a string ID relates to a particular slot type. My proposed API was just an example to demonstrate the concept of having the callsite and the definition site be statically linked which your new API also does but in a different way 👍

It would be good if you could add some examples that address the following scenarios:

• Non-slot children being rendered alongside or inside of slot children
• Rendering a slot inside a slot

[nihgwu]

@tom-sherman Added

[nihgwu]

here is the demo to build a tree from Slots, with create-slots vs with react-call-return
Checkout the console.log you will find how clean it will be if it's built in React core, as in user space we have no way to know the index when inserting an item, so I have to rescan the children of a host, then it results in lots of force update

[stefee]

This is an interesting proposal. I'm a relatively uninformed reader of this, so perhaps an ignorant question:

I'm trying to understand what is enabled by this that is not possible using props. For example:

functionMyComponent({ firstEl, lastEl }){return<div>{firstEl}<p>Hello</p>{lastEl}</div>;}

The 'slots' here are passed as React elements into the component as props.

[tom-sherman]

@stefee This is a completely legitimate confusion, I think the RFC needs to improve a bit on the example side to showcase what problem this solves at a glance.

My mental model for this problem space is based around the <select>/<option> component API, this is excellently described in @reach-ui/descendants: https://github.com/reach/reach-ui/tree/dev/packages/descendants#the-problem

I think it would be worth bringing this example into this RFC pretty much verbatim.

Another important note is that this is an API targeted primarily at library developers. I wouldn't expect to see it used too much in apps.

Hopefully this explains it better!

[nihgwu]

@stefee that's a good question, TLDR: yes you can do it and that's the cheapest approach for app devs, but for ui library authors it's not a good API IMO, and the proposal is much powerful, like A11y and virtualisation support.

Think about how would you support A11y in your approach? Consume context in each slot? Which is the approach for most libraries like radix-ui, but you can see how simple it is with this proposal, the id is already in the JSX tree, why do we need a double render to get it? IoC means a lot.

In terms of Virtualisation, you can find more context in this thread, but you can take it as a tree info collector without rendering the tree to real DOM, so it will enable more possibilities.

Also this proposal is much closer to the Slots in Web Components and we don't need to use a static prop(slot) to achieve that.

[nihgwu]

@tom-sherman Yes I agree the examples need to be improved, but I'm afraid it will prolong the content a lot if I include the content of https://github.com/reach/reach-ui/tree/dev/packages/descendants#the-problem while I've provide the links there, but probably I should highlight those links to make them more accessible

[tom-sherman]

Understood, maybe just highlighting the link more in a more prominent position is the way to go.

To be clear I wasn't suggesting including the different "options" from that doc, just the problem statement section. I think <Menu>/<MenuItem> is the easiest to understand use case.

[jlarmstrongiv]

Slots are definitely a feature I miss in React, having worked with Vue and Web Components.

First-party support for the Slots API would be great! This RFC would avoid the force-updates and enable slots to be used with React Server Components.

[giuseppelt]

Just as proof-of-concept, I wrote a very simple Slot component.
https://www.breakp.dev/blog/simple-slot-system-for-react/

Maybe not the best solution, but just something to add into the mix.

[desko27]

This is an excellent idea. I've been using React for years and I feel like slots could've helped me in a variety of scenarios where it felt too hacky to achieve true composability. It can be done, but it's sometimes not easily, and definitely not clean.

I mean, articles like the one from@kentcdodds show the unquestionable benefits of composable components, but trying to build one can make you feel kind of abandoned/unsupported by the framework itself, as if you were going against it.

Today I found create-slots and this RFC. I just started using it and I built a clean composable card component in no time. Feels very native and looks so maintainable. Also TS support is excellent.

A nice API that solves a real problem. This is the way. TY @nihgwu, I'd love to see this built in React.

[Flammae]

As someone who independently developed my solution for integrating slots into React even before discovering this RFC, I would like to discuss my implementation here to bring a fresh perspective and talk about some other challenges with this and my own design.

My implementation focuses on a simplistic and type-safe API, closely resembling implementations from other frameworks, especially Vue.js.

Implementation

typeListItemProps={children: SlotChildren<|Slot<"title">// Shorthand of Slot<"title", {}>|Slot<"thumbnail">// Shorthand of Slot<"thumbnail", {}>|Slot<{isExpanded: boolean}>// Shorthand of Slot<"default", {isExpanded: boolean}>>;};functionListItem({ children }: ListItemProps){const{ slot, hasSlot }=useSlot(children);// Slot and hasSlot object inferred from children.return(<li>{/* Render thumbnail if provided, otherwise nothing*/}<slot.thumbnail/><div>{/* Render a fallback if title is not provided*/}<slot.title>Expand for more</slot.title>{/* Render the description and pass the prop up to the parent */}<slot.defaultisExpanded={dynamicValue}/></div></li>);}

Here, I used a build plugin to change slot elements into function invocations at build time. This is because slots require access to children with closure and thus need to be created for every component. If this feature were built into React, useSlot would not need to accept children as an argument but would be able to access it with a context-like API, eliminating the need for a custom build plugin. Slots could also just be a function, but syntactic sugar is just too good to say no to.

Cool Things (So Far):

• We type children directly. While TypeScript can't enforce a strict shape for JSX, it can still help enforce strict type checking for strings, numbers, functions (implicit default slots). It can also strictly type check elements created with React.createElement.

Drawbacks (So Far):

• Already more opinionated than OP implementation

Usage from parent

slot-name attribute (Not type-safe)

<ListItem><imgslot-name="thumbnail"src="..."/><divslot-name="title">A title</div>
this is a description.
</ListItem>

Everything with a slot-name attribute goes inside its corresponding slots. It's hyphenated because TypeScript doesn't enforce hyphenated attributes, which is important when you want to specify slot-name on a custom component. Content without a slot-name attribute implicitly lands in the default slot.

Templates (Optionally type-safe)

import{template}from"...";// Or import{createTemplate}from"...";consttemplate=createTemplate<ListItemProps["children"]>();<ListItem><template.thumbnail><imgsrc="..."/></template.thumbnail><template.title>A title</template.title><template.description>{({ isExpanded })=>isExpanded ? <strong>A description</strong> : "A description"}</template.description><template.description>doesn't have to be a function</template.description></ListItem>

Templates are adopted from Vue's design. They can be made type-safe with createTemplate, and they also provide a way to access props passed up from a child, which is also common in other frameworks.

Drawbacks:

• Templates aren't rendered; they just specify content for corresponding slots. Instead, fragments are rendered in their place to maintain key equality.

Enforcing the Node Type and Advanced Logic

In my library, there are OverrideNode elements that can be included as a direct child of slot elements to specify advanced override logic for specific slots and their fallbacks. I won't get into it here because I believe the OverrideNode API is too funky and opinionated for React. Instead, a similar API can be implemented this way, if it ever was considered to be used in this PR:

functionListItem({ children }: ListItemProps){const{ slot, hasSlot }=useSlot(children);// Slot and hasSlot object inferred from children.// Called for Each node for this slotconstSlotWithOverride=React.Children.overrideSlot(slot.thumbnail,(node)=>{// Enforce final node type// Add props// Change type})return(<li>{/* Render thumbnail if provided, otherwise nothing*/}<SlotWithOverride/><div>{/* Render a fallback if title is not provided*/}<slot.title>Expand for more</slot.title>{/* Render the description and pass the prop up to the parent */}<slot.defaultisExpanded={dynamicValue}/></div></li>);}

This design also opens the door for type-safe composition between two slotted components. EG: Render parent-provided content for the default slot inside the child's "foo" slot and pass up or override the props specified on a child's slot. I will also not get into this here.

Final Thoughts

There are a couple of things with the slot pattern that break how rendering and existing APIs work in React:

• My implementation, and I believe the OP's implementation (to a lesser degree), cannot meaningfully work with React.Children APIs. This is because the shape of children is unique to useSlot (mine) or createHost (OP's), and it can only be understood fully within the context of our wrappers. In my case, React.Children APIs need to prevent any kind of modification of templates and their children, potentially by skipping the iteration. This is especially true for templates with functional children because the function needs to only be called internally.
• Because children is flattened and mapped over to collect the content for specific slots, this changes how the keys should work for entire children. Here's the link to the docs that explains this drawback in my own API. I believe this is also true for this implementation as well.

I'm very passionate about slots and the fresh new patterns it brings to our toolchain. My point was not to undermine this RFC but to bring the new ideas in and document issues that there might be to make it even better. I would love it if React supported slots natively.

If anyone wants to check out my implementation, it can be found here

[nihgwu]

@Flammae Thanks for the details comment, will take more time to understand your lib

Because children is flattened and mapped over to collect the content for specific slots

this is not the case for my impl, I avoided iteration and only rely on React's render mechanism to collect slots, so it just works as long as you don't render extra nodes around slots, so the following still works as tooltip is rendered by createPortal

constItem=()=><Tooltip><List.Item/></Tooltip>constlist=<List><Item/></List>

[Flammae]

What happens if the tooltip was used this way:

<List>{[<Itemkey={1}>First</Item>,<Itemkey={2}>Second</Item>]}{[<Itemkey={1}>Third</Item>,<Itemkey={2}>Fourth</Item>]}<Itemkey={1}>Fifth</Item><Item>Without key</Item></List>

And what if the tooltip accepted another slot, Thumbnail, and it was inserted and reordered this way on the subsequent render:

<List>{[<Itemkey={2}>Fourth</Item>,<Thumbnailkey={3}/>,<Itemkey={1}>Third</Item>]}<Itemkey={1}>Fifth</Item><Item>Without Key</Item>{[<Itemkey={2}>Second</Item>,<Itemkey={1}>First</Item>,<Itemkey={3}>New Item</Item>]}</List>

Would it be able to correctly identify which nodes to update and which nodes to re-render?

The correct solution should do this:

• Items should be updated to be in the order specified: Fourth, Third, Fifth, Without Key, Second, First, New Item
• The Item without key should re-render, "New Item" should mount, the other items, including "Fifth" should just be updated
• Thumbnail should render in its own slot

Also, if our goal is to not break existing React logic, the items that were previously inside the array and on the subsequent render were outside, or nested deeper, should re-render even if the keys are the same.

To clarify, by re-render I mean unmount and remount

Edit:

I was wrong in thinking React maintains key equality when arrays themselves change positions. What's important is to maintain key equality when arrays stay in the same position and items within the array move. This implementation definitely handles Key equality right!:

Here's the test: (npm run test)
https://stackblitz.com/edit/vitejs-vite-cbevwa?file=src%2FSelect.jsx,package.json,test%2Findex.test.jsx,src%2FApp.jsx,public%2Fvite.svg&terminal=dev

[nihgwu]

@Flammae for your first question, you can try it here

for the second one, you can try it locally, the thumbnail will be rendered outside of list, and you will see a warning in console on dev env

[dante01yoon]

Do we have any further discussion so far?

[dante01yoon]

Or any plan to implement this in upcoming React release (19, 20..?)

[dante01yoon]

@will-stone do you have any reason just put thumbs down?

[will-stone]

@dante01yoon There will be lots of people subscribed to this thread, and you just pinged them all, thrice. It’s generally best not to ask for updates on these things, as updates will be posted here when they are ready. Asking for updates is like posting “+1” and doesn’t benefit the discussion. Thanks 🙂 (and no need to reply to this message, which will notify everyone again 😅).

[dante01yoon]

Agree in some aspect, but someone may want to know any further discussion happens in somewhere place since discussion suddenly hanged since end of last year. As this didn't mean to spam, IMHO we shouldn't stop those want to ask any updates. Anyways, thanks again for your kindness.

[mendrik]

not sure if this helps anything but I had a rather simple implementation of slots like so:

import{typeFunctionComponent,typePropsWithChildren,typeReactNode,useRef}from'react'import{groupBy,mapObjIndexed,path,pipe,prop}from'ramda'importtype{Fn}from'src/contexts/types'exporttypeSlots<Textendsstring>={[SinT]: FunctionComponent<{/**/}>}exporttypeSlotChildren<T>=T&{children: Iterable<ReactNode>}exportconstuseGetSlots: <Textendsstring>(children: Iterable<ReactNode>)=>Slots<T>=pipe(groupBy(path(['type','displayName'])asany),mapObjIndexed((items: ReactNode[])=>()=>items[0])asFn<Slots<any>>,useRef,prop('current')asFn<Slots<any>>)constslotFactory=newProxy({},{get<Textendsstring,PextendskeyofSlots<T>&string>(_target: object,p: P,_receiver: any): Slots<T>[P]{constcomp=({ children }: PropsWithChildren<Parameters<Slots<T>[P]>>)=><>{children}</>comp.displayName=preturncompasSlots<T>[P]}})exportconstuseSlots=<Textendsstring>(): Slots<T>=>slotFactoryasSlots<T>

which can then be used like so in the parent component:

const{ Header, Main, Side }=useSlots<SidePanelPageSlots>()return(<SidePanelPage><Header><div>Whatevercontentcangohere</div></Header><Main>Main</Main><Side>Side</Side></SidePanelPage>)

and SidePanelPage is then defined like so:

exporttypeSidePanelPageSlots='Header'|'Main'|'Side'exportconstSidePanelPage=({ mainTitle, sideTitle, children }: SlotChildren<OwnProps>)=>{const{ Header, Main, Side }=useGetSlots<SidePanelPageSlots>(children)return(<div><divclassName="header"><Header/></div><divclassName="main"><Main/></div><divclassName="side"><Side/></div></div>)}

since getSlots operates on children, slots must be still a first descendant. But since one can use those slots where-ever (see SidePanelPage) it should not have any downside.

[amadsen]

I think the React 19 documentation of <title>, <script>, <meta>, and <link> illustrates the usefulness of a good slots API quite well. Note that none of them rely on render props nor on being direct children of the slotted component. Each of these components are (conditionally) hoisted in to the head of the document because that's the location they belong in, but the data in them isn't known when that set of components / dom nodes has to be rendered. Many UI patterns also exhibit this behavior.

I've built my own slots implementation that does this by:

1. calling makeSlot(SomeBaseComponent), which returns a SlotContainer component (this could also be called SlotFill component) which can be exported / imported and is used to pass (typed) children in to a slot.
2. calling const { Slotted, SlotChildren, ...variousSlotPositionComponents } = useSlot(slots, children) within the slotted / host component.
3. The slotted / host component returns JSX as normal, with Slotted somewhere in its returned element tree and the various SlotPosition components and SlotChildren passed as children of Slotted. The returned JSX acts as the template to position the slots. (SlotChildren is essentially a SlotPosition component for the original children that may just be complicating the API.)

Internally the SlotContainer uses a slot specific context - provided by the Slotted component - to dispatch its children (originally synchronously, via useSyncExternalStore) to the associated SlotPosition component.

This worked for React 19.1, both for SSR and client rendering. Then React 19.2 changed server side rendering internals to be more like the client and I had to introduce an async server component that does nothing more than resolve a promise - conditionally, based on the existence of a request context - to ensure that children, and therefore SlotContainers, completed rendering before the SlotPosition components. However, React 19.2 also surfaced an error complaining about the synchronous dispatch causing a rerender of the SlotPosition Component during the render of another component. Using queueMicrotask (or Promise.resolve().then()) to notify the SlotPosition components resolves that issue, but - even though the SlotPosition components can read the updated children in useLayoutEffect and are rerendered before the original hydrated component is compared, the need for a two-phase render on the client makes hydration errors difficult to avoid if a SlotPosition component is rendered before the SlotChildren component (as in, I haven't figured out how to do it.)

If there is or was some way to mark a render during hydration as dependent on the results of its children, or as transitional (but apparently in some way not the same as startTransition) and therefore not the final hydration state it would allow for what I think is a very nice hoisting slot API.

[amadsen]

A const prerendered = usePreRenderChildren(children) hook would be an interesting way to do it. The existing Children.map() API doesn't quite work because, as called out in its documentation, it only iterates over the element objects representing the children - which are intended to be opaque. Even if we ignore that intention of opacity, unless we actually render the children (mounting isn't necessary) we can't pick up the children that they add to the tree. (I'm testing with a wouter router that renders a component per route if the route matches. That route specific component actually adds the SlotContainers for a wrapping slot host.)