Typing Component Props

This is intended as a basic orientation and reference for React developers familiarizing with TypeScript.

Basic Prop Types Examples

A list of TypeScript types you will likely use in a React+TypeScript app:

type AppProps = {
  message: string;
  count: number;
  disabled: boolean;
  /** array of a type! */
  names: string[];
  /** string literals to specify exact string values, with a union type to join them together */
  status: "waiting" | "success";
  /** an object with known properties (but could have more at runtime) */
  obj: {
    id: string;
    title: string;
  };
  /** array of objects! (common) */
  objArr: {
    id: string;
    title: string;
  }[];
  /** any non-primitive value - can't access any properties (NOT COMMON but useful as placeholder) */
  obj2: object;
  /** an interface with no required properties - (NOT COMMON, except for things like `React.Component<{}, State>`) */
  obj3: {};
  /** a dict object with any number of properties of the same type */
  dict1: {
    [key: string]: MyTypeHere;
  };
  dict2: Record<string, MyTypeHere>; // equivalent to dict1
  /** function that doesn't take or return anything (VERY COMMON) */
  onClick: () => void;
  /** function with named prop (VERY COMMON) */
  onChange: (id: number) => void;
  /** function type syntax that takes an event (VERY COMMON) */
  onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
  /** alternative function type syntax that takes an event (VERY COMMON) */
  onClick(event: React.MouseEvent<HTMLButtonElement>): void;
  /** any function as long as you don't invoke it (not recommended) */
  onSomething: Function;
  /** an optional prop (VERY COMMON!) */
  optional?: OptionalType;
  /** when passing down the state setter function returned by `useState` to a child component. `number` is an example, swap out with whatever the type of your state */
  setState: React.Dispatch<React.SetStateAction<number>>;
};

object as the non-primitive type

object is a common source of misunderstanding in TypeScript. It does not mean "any object" but rather "any non-primitive type", which means it represents anything that is not number, bigint, string, boolean, symbol, null or undefined.

Typing "any non-primitive value" is most likely not something that you should do much in React, which means you will probably not use object much.

Empty interface, {} and Object

An empty interface, {} and Object all represent "any non-nullish value"—not "an empty object" as you might think. Using these types is a common source of misunderstanding and is not recommended.

interface AnyNonNullishValue {} // equivalent to `type AnyNonNullishValue = {}` or `type AnyNonNullishValue = Object`

let value: AnyNonNullishValue;

// these are all fine, but might not be expected
value = 1;
value = "foo";
value = () => alert("foo");
value = {};
value = { foo: "bar" };

// these are errors
value = undefined;
value = null;

Useful React Prop Type Examples

Relevant for components that accept other React components as props.

export declare interface AppProps {
  children?: React.ReactNode; // best, accepts everything React can render
  childrenElement: React.JSX.Element; // A single React element
  style?: React.CSSProperties; // to pass through style props
  onChange?: React.FormEventHandler<HTMLInputElement>; // form events! the generic parameter is the type of event.target
  //  more info: https://react-typescript-cheatsheet.netlify.app/docs/advanced/patterns_by_usecase/#wrappingmirroring
  props: Props & React.ComponentPropsWithoutRef<"button">; // to impersonate all the props of a button element and explicitly not forwarding its ref
  props2: Props & React.ComponentPropsWithRef<MyButtonWithForwardRef>; // to impersonate all the props of MyButtonForwardedRef and explicitly forwarding its ref
}

Small React.ReactNode edge case before React 18

Before the React 18 type updates, this code typechecked but had a runtime error:

type Props = {
  children?: React.ReactNode;
};

function Comp({ children }: Props) {
  return <div>{children}</div>;
}
function App() {
  // Before React 18: Runtime error "Objects are not valid as a React child"
  // After React 18: Typecheck error "Type '{}' is not assignable to type 'ReactNode'"
  return <Comp>{{}}</Comp>;
}

This is because ReactNode includes ReactFragment which allowed type {} before React 18.

Thanks @pomle for raising this.

React.JSX.Element vs React.ReactNode?

Quote @ferdaber: A more technical explanation is that a valid React node is not the same thing as what is returned by React.createElement. Regardless of what a component ends up rendering, React.createElement always returns an object, which is the React.JSX.Element interface, but React.ReactNode is the set of all possible return values of a component.

• React.JSX.Element -> Return value of React.createElement
• React.ReactNode -> Return value of a component

More discussion: Where ReactNode does not overlap with React.JSX.Element

Something to add? File an issue.

Types or Interfaces?

You can use either Types or Interfaces to type Props and State, so naturally the question arises - which do you use?

TL;DR

Use Interface until You Need Type - orta.

More Advice

Here's a helpful rule of thumb:

• always use interface for public API's definition when authoring a library or 3rd party ambient type definitions, as this allows a consumer to extend them via declaration merging if some definitions are missing.

• consider using type for your React Component Props and State, for consistency and because it is more constrained.

You can read more about the reasoning behind this rule of thumb in Interface vs Type alias in TypeScript 2.7.

The TypeScript Handbook now also includes guidance on Differences Between Type Aliases and Interfaces.

Note: At scale, there are performance reasons to prefer interfaces (see official Microsoft notes on this) but take this with a grain of salt

Types are useful for union types (e.g. type MyType = TypeA | TypeB) whereas Interfaces are better for declaring dictionary shapes and then implementing or extending them.

Useful table for Types vs Interfaces

It's a nuanced topic, don't get too hung up on it. Here's a handy table:

Aspect	Type	Interface
Can describe functions	✅	✅
Can describe constructors	✅	✅
Can describe tuples	✅	✅
Interfaces can extend it	⚠️	✅
Classes can extend it	🚫	✅
Classes can implement it (implements)	⚠️	✅
Can intersect another one of its kind	✅	⚠️
Can create a union with another one of its kind	✅	🚫
Can be used to create mapped types	✅	🚫
Can be mapped over with mapped types	✅	✅
Expands in error messages and logs	✅	🚫
Can be augmented	🚫	✅
Can be recursive	⚠️	✅

⚠️ In some cases

(source: Karol Majewski)

Something to add? File an issue.