When to use JSX.Element vs ReactNode vs ReactElement?

I am currently migrating a React application to TypeScript. So far, this works pretty well, but I have a problem with the return types of my render functions, specifically in my functional components.

I have always used JSX.Element as the return type, now this doesn't work any more if a component decides to not render anything, i.e. returns null, since null is not a valid value for JSX.Element. This was the beginning of my journey. I searched the web and found that you should use ReactNode instead, which includes null and a few other things that can happen.

However, when creating a functional component, TypeScript complains about the ReactNode type. Again, after some searching I found, that for functional components you should use ReactElement instead. However, if I do so, the compatibility issue is gone, but now TypeScript again complains about null not being a valid value.

To cut a long story short, I have three questions:

• What is the difference between JSX.Element, ReactNode, and ReactElement?

• Why do the render methods of class components return ReactNode but functional components return ReactElement?

• How do I solve this with respect to null?

What is the difference between JSX.Element, ReactNode, and ReactElement?

A ReactElement is an object with type, props, and key properties:
interface ReactElement {
type: T;
props: P;
key: string | null;
}


A JSX.Element is a ReactElement. It exists as various libraries can implement JSX in their own way:
declare global {
// …
namespace JSX {
// …
interface Element extends React.ReactElement {}
// …
}
// …
}


A ReactPortal is a ReactElement with a children property:
interface ReactPortal extends ReactElement {
children: ReactNode;
}


A ReactNode is a ReactElement, string, number, Iterable, ReactPortal, boolean, null, or undefined:
type ReactNode =
| ReactElement
| string
| number
| Iterable
| ReactPortal
| boolean
| null
| undefined;


Example:
// //



Why do the render methods of class components return ReactNode, but function components return ReactElement?

This is due to historical reasons.

A Component.render returns a ReactNode:
class Component {
// …
render(): ReactNode;
// …
}


A FunctionComponent returns a ReactElement | null:
interface FunctionComponent {
(props: PropsWithChildren, context?: any): ReactElement | null;
propTypes?: WeakValidationMap | undefined;
contextTypes?: ValidationMap | undefined;
defaultProps?: Partial | undefined;
displayName?: string | undefined;
}


How do I solve this with respect to null?

Type it as ReactElement | null just as React does. Or let TypeScript infer the type.

Stack Overflow Q#58123398, score: 926