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

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.

Beginne mit der Seite „Understanding your UI as a tree“ und sieh dir das Beispiel InspirationGenerator an, insbesondere den direkt gerenderten FancyText und das auf props.children basierende Copyright-Kind. Ermittle, ob die Dokumentation den Unterschied bei der Darstellung erklären oder auf eine weiterführende Ressource zur Optimierung verlinken sollte. Als erledigt gilt die Aufgabe, wenn die Seite den Unterschied korrekt behandelt oder das beabsichtigte vereinfachte Modell klar erklärt.