[Suggestion]: Documentation does not make mention of the difference between `props.children` and directly rendering children as it relates to rendering behaviour.

[dwjohnston]

Summary

Here I have an example of two ways we can create functionally identical components.

export function ChildrenStyleOne() {
    const [value, setValue] = useState('');
    return <div id="foo">
        <SomeThing />
    </div>
}

export function ChildrenStyleTwo(props: React.PropsWithChildren) {
    const [value, setValue] = useState('');
    return <div id="bar">
        {props.children}
    </div>
}

However, there is an important different in how these components behave as far as rendering behaviour goes.

In the first style, every render of ChildrenStyleOne (eg. say because state is changing), will also cause a render of SomeThing.

In the second style, additional renders of ChildrenStyleTwo will not cause renders of the {props.children}.

This is a useful distinction to be aware of - using the props.children/slots approach is a simple mechanism to avoid full branch renders.

I've observed people commonly believing that 'every time a context provider's state changes, everything below it will render' - and I believe this misconception arrises from not being aware of this difference in rendering behaviour.

Page

https://react.dev/learn/understanding-your-ui-as-a-tree

Details

The docs above actually serve to reinforce the conflation of directly rendered children,and props.children.

For example the example code includes this node:

      <InspirationGenerator>
        <Copyright year={2004} />
      </InspirationGenerator>

and the render tree diagram looks like this:

We can see that FancyText here is a directly rendered child, while Copyright is a props.children child.

The render tree described in the docs makes no distinction between the two.

I imagine this is likely a deliberate decision on the the part of the React maintainers - simplifying the conceptual model. If that's the case, is there a blog post or something that talks about what the strategy is?

The docs perhaps could do with a deep dive note that makes mention of this distinction or links to a more comprehensive optimisation section elsewhere.