Type Reference

A reference for all the utility Flow types exported by the React module

React exports a handful of utility types that may be useful to you when typing advanced React patterns. In previous sections we have seen a few of them. The following is a complete reference for each of these types along with some examples for how/where to use them.

Table of contents:

These types are all exported as named type exports from the react module. If you want to access them as members on the React object (e.g. React.Node or React.StatelessFunctionalComponent) and you are importing React as an ES module then you should import React as a namespace:

1
 
import * as React from 'react';

If you are using CommonJS you can also require React:

1
 
const React = require('react');

You can also used named type imports in either an ES module environment or a CommonJS environment:

1
 
import type {Node} from 'react';

We will refer to all the types in the following reference as if we imported them with:

1
 
import * as React from 'react';

Note: While importing React with a default import works:

import React from 'react';

You will have access to all of the values that React exports, but you will not have access to the types documented below! This is because Flow will not add types to a default export since the default export could be any value (like a number). Flow will add exported named types to an ES namespace object which you can get with import * as React from 'react' since Flow knows if you export a value with the same name as an exported type.

Again, if you import React with: import React from 'react' you will be able to access React.Component, React.createElement(), React.Children, and other JavaScript values. However, you will not be able to access React.Node, React.ChildrenArray or other Flow types. You will need to use a named type import like: import type {Node} from 'react' in addition to your default import.

React.Node

This represents any node that can be rendered in a React application. React.Node can be undefined, null, a boolean, a number, a string, a React element, or an array of any of those types recursively.

If you need a return type for your component render() methods or you need a generic type for a children prop then you should use React.Node.

Here is an example of React.Node being used as the return type to render():

1
2
3
4
5
 
class MyComponent extends React.Component<{}> {
  render(): React.Node {
    // ...
  }
}

It may also be used as the return type of a stateless functional component:

1
2
3
 
function MyComponent(props: {}): React.Node {
  // ...
}

You don’t need to annotate the return type of either your render() method or a stateless functional component. However, if you want to annotate the return type then React.Node is the generic to use.

Here is an example of React.Node as the prop type for children:

1
2
3
 
function MyComponent({ children }: { children: React.Node }) {
  return <div>{children}</div>;
}

All react-dom JSX intrinsics have React.Node as their children type. <div>, <span>, and all the rest.

The definition of React.Node can be roughly approximated with a React.ChildrenArray<T>:

1
 
type Node = React.ChildrenArray<void | null | boolean | string | number | React.Element<any>>;

React.Element<typeof Component>

A React element is the type for the value of a JSX element:

1
 
const element: React.Element<'div'> = <div />;

React.Element<typeof Component> is also the return type of React.createElement().

A React.Element<typeof Component> takes a single type argument, typeof Component. typeof Component is the component type of the React element. For an intrinsic element, typeof Component will be the string literal for the intrinsic you used. Here are a few examples with DOM intrinsics:

1
2
3
 
(<div />: React.Element<'div'>); // OK
(<span />: React.Element<'span'>); // OK
(<div />: React.Element<'span'>); // Error: div is not a span.

typeof Component can also be your React class component or stateless functional component.

1
2
3
4
5
6
 
class Foo extends React.Component<{}> {}
function Bar(props: {}) {}

(<Foo />: React.Element<typeof Foo>); // OK
(<Bar />: React.Element<typeof Bar>); // OK
(<Foo />: React.Element<typeof Bar>); // Error: Foo is not Bar

Take note of the typeof, it is required! Foo without typeof would be the type of an instance of Foo. So: (new Foo(): Foo). We want the type of Foo not the type of an instance of Foo. So: (Foo: typeof Foo). Class<Foo> would also work here, but we prefer typeof for consistency with stateless functional components.

We also need typeof for Bar because Bar is a value. So we want to get the type of the value Bar. (Bar: Bar) is an error because Bar cannot be used as a type, so the following is correct: (Bar: typeof Bar).

React.ChildrenArray<T>

A React children array can be a single value or an array nested to any level. It is designed to be used with the React.Children API.

For example if you want to get a normal JavaScript array from a React.ChildrenArray<T> see the following example:

1
2
3
4
5
6
7
8
9
 
import * as React from 'react';

// A children array can be a single value...
const children: React.ChildrenArray<number> = 42;
// ...or an arbitrarily nested array.
const children: React.ChildrenArray<number> = [[1, 2], 3, [4, 5]];

// Using the `React.Children` API can flatten the array.
const array: Array<number> = React.Children.toArray(children);

React.ComponentType<Props>

This is a union of a class component or a stateless functional component. This is the type you want to use for functions that receive or return React components such as higher-order components or other utilities.

Here is how you may use React.ComponentType<Props> with React.Element<typeof Component> to construct a component with a specific set of props:

1
2
3
4
5
6
7
8
9
10
 
type Props = {
  foo: number,
  bar: number,
};

function createMyElement<C: React.ComponentType<Props>>(
  Component: C,
): React.Element<C> {
  return <Component foo={1} bar={2} />;
}

React.ComponentType<Props> does not include intrinsic JSX element types like div or span. See React.ElementType if you also want to include JSX intrinsics.

The definition for React.ComponentType<Props> is roughly:

1
2
3
 
type ComponentType<Props> =
  | React.StatelessFunctionalComponent<Props>
  | Class<React.Component<Props, any>>;

React.StatelessFunctionalComponent<Props>

This is the type of a React stateless functional component.

The definition for React.StatelessFunctionalComponent<Props> is roughly:

1
2
 
type StatelessFunctionalComponent<Props> =
  (props: Props) => React.Node;

There is a little bit more to the definition of React.StatelessFunctionalComponent<Props> for context and props.

React.ElementType

Similar to React.ComponentType<Props> except it also includes JSX intrinsics (strings).

The definition for React.ElementType is roughly:

1
2
3
 
type ElementType =
  | string
  | React.ComponentType<any>;

React.Key

The type of the key prop on React elements. It is a union of strings and numbers defined as:

1
 
type Key = string | number;

React.Ref<typeof Component>

The type of the ref prop on React elements. React.Ref<typeof Component> could be a string or a ref function.

The ref function will take one and only argument which will be the element instance which is retrieved using React.ElementRef<typeof Component> or null since React will pass null into a ref function when unmounting.

Like React.Element<typeof Component>, typeof Component must be the type of a React component so you need to use typeof as in React.Ref<typeof MyComponent>.

The definition for React.Ref<typeof Component> is roughly:

1
2
3
 
type Ref<C> =
  | string
  | (instance: React.ElementRef<C> | null) => mixed;

React.ElementProps<typeof Component>

Gets the props for a React element type. Type could be a React class component, a stateless functional component, or a JSX intrinsic string. This type is used for the props property on React.Element<typeof Component>.

Like React.Element<typeof Component>, Type must be the type of a React component so you need to use typeof as in React.ElementProps<typeof MyComponent>.

React.ElementConfig<typeof Component>

Like React.ElementProps<typeof Component> this utility gets the type of a component’s props but without the defaultProps!

For example,

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
import * as React from 'react';

class MyComponent extends React.Component<{foo: number}> {
  static defaultProps = {foo: 42};

  render() {
    return this.props.foo;
  }
}

// `React.ElementProps<>` requires `foo` even though it is a `defaultProp`.
({foo: 42}: React.ElementProps<typeof MyComponent>);

// `React.ElementConfig<>` does not require `foo` since it is a `defaultProp`.
({}: React.ElementConfig<typeof MyComponent>);

Like React.Element<typeof Component>, Type must be the type of a React component so you need to use typeof as in React.ElementProps<typeof MyComponent>.

React.ElementRef<typeof Component>

Gets the instance type for a React element. The instance will be different for various component types:

  • React class components will be the class instance. So if you had class Foo extends React.Component<{}> {} and used React.ElementRef<typeof Foo> then the type would be the instance of Foo.
  • React stateless functional components do not have a backing instance and so React.ElementRef<typeof Bar> (when Bar is function Bar() {}) will give you the undefined type.
  • JSX intrinsics like div will give you their DOM instance. For React.ElementRef<'div'> that would be HTMLDivElement. For React.ElementRef<'input'> that would be HTMLInputElement.

Like React.Element<typeof Component>, Type must be the type of a React component so you need to use typeof as in React.ElementRef<typeof MyComponent>.

← Redux

Was this guide helpful? Let us know by sending a message to @flowtype.