francisfuzz's engineering blog

What I wish was explained in React.createElement docs

In a recent code review, my friend asked about my note for React.createElement:

gr2m-code-review-react-create-element

I re-read my work and confessed that I just copied this straight from the API Reference > React > createElement() docs:

create-element-docs-snippet

The funny thing is that the documentation is clear around what type can be, but not so for its props and children parameters.

I wanted to learn more about what this might actually mean, so I found the exported function to check how it processes children -- the note at the top of the relevant block was particularly illuminating:

  // Children can be more than one argument, and those are transferred onto
// the newly allocated props object.
const childrenLength = arguments.length - 2;
if (childrenLength === 1) {
props.children = children;
} else if (childrenLength > 1) {
const childArray = Array(childrenLength);
for (let i = 0; i < childrenLength; i++) {
childArray[i] = arguments[i + 2];
}
if (__DEV__) {
if (Object.freeze) {
Object.freeze(childArray);
}
}
props.children = childArray;
}

My understanding of this:

From that context, I think that [...children] may have been some shorthand expression to say "yeah, there can actually be more than one child here, so go get them all and put them in an array."

Checking the Git blame, the commit that introduced these docs don't tell us much since it was just a commit right on main.

Admittedly, I didn't look into props and how that's handled, though this could be a great opportunity to document both (or, at the very least field an issue) for others to look into! 😉