React and TypeScript Cheatsheets

Basic Cheatsheet Table of Contents #

Section 1: Setup TypeScript with React #

Prerequisites #

1. good understanding of React
2. familiarity with TypeScript Types (2ality's guide is helpful. If you’re an absolute beginner in TypeScript, check out chibicode’s tutorial.)
3. having read the TypeScript section in the official React docs.
4. having read the React section of the new TypeScript playground (optional: also step through the 40+ examples under the playground's Examples section)

This guide will always assume you are starting with the latest TypeScript version. Notes for older versions will be in expandable <details> tags.

React + TypeScript Starter Kits #

Cloud setups:

• TypeScript Playground with React just if you are debugging types (and reporting issues), not for running code
• CodeSandbox - cloud IDE, boots up super fast
• Stackblitz - cloud IDE, boots up super fast

Local dev setups:

• Next.js: npx create-next-app -e with-typescript will create in your current folder
• Create React App: npx create-react-app name-of-app --template typescript will create in new folder
• Meteor: meteor create --typescript name-of-my-new-typescript-app
• Ignite for React Native: ignite new myapp
• TSDX: npx tsdx create mylib for Creating React+TS libraries. (in future: TurboRepo)

Import React #

import * as React from "react";
import * as ReactDOM from "react-dom";

This is the most futureproof way to import React. If you set --allowSyntheticDefaultImports (or add "allowSyntheticDefaultImports": true) in your tsconfig.json you can use more familiar imports:

import React from "react";
import ReactDOM from "react-dom";

Section 2: Getting Started #

Function Components #

These can be written as normal functions that take a props argument and return a JSX element.

// Declaring type of props - see "Typing Component Props" for more examples
type AppProps = {
  message: string;
}; /* use `interface` if exporting so that consumers can extend */

// Easiest way to declare a Function Component; return type is inferred.
const App = ({ message }: AppProps) => <div>{message}</div>;

// you can choose annotate the return type so an error is raised if you accidentally return some other type
const App = ({ message }: AppProps): JSX.Element => <div>{message}</div>;

// you can also inline the type declaration; eliminates naming the prop types, but looks repetitive
const App = ({ message }: { message: string }) => <div>{message}</div>;

const App: React.FunctionComponent<{ message: string }> = ({ message }) => (
  <div>{message}</div>
);

const Title: React.FunctionComponent<{ title: string }> = ({
  children,
  title,
}) => <div title={title}>{children}</div>;

type Props = { foo: string };

// OK now, in future, error
const FunctionComponent: React.FunctionComponent<Props> = ({
  foo,
  children,
}: Props) => {
  return (
    <div>
      {foo} {children}
    </div>
  ); // OK
};

// Error now, in future, deprecated
const VoidFunctionComponent: React.VoidFunctionComponent<Props> = ({
  foo,
  children,
}) => {
  return (
    <div>
      {foo}
      {children}
    </div>
  );
};

const MyConditionalComponent = ({ shouldRender = false }) =>
  shouldRender ? <div /> : false; // don't do this in JS either
const el = <MyConditionalComponent />; // throws an error

const MyArrayComponent = () => Array(5).fill(<div />);
const el2 = <MyArrayComponent />; // throws an error

const MyArrayComponent = () => (Array(5).fill(<div />) as any) as JSX.Element;

Hooks #

Hooks are supported in @types/react from v16.8 up.

useState #

Type inference works very well most of the time:

const [val, toggle] = React.useState(false);
// `val` is inferred to be a boolean
// `toggle` only takes booleans

See also the Using Inferred Types section if you need to use a complex type that you've relied on inference for.

However, many hooks are initialized with null-ish default values, and you may wonder how to provide types. Explicitly declare the type, and use a union type:

const [user, setUser] = React.useState<IUser | null>(null);

// later...
setUser(newUser);

useReducer #

You can use Discriminated Unions for reducer actions. Don't forget to define the return type of reducer, otherwise TypeScript will infer it.

const initialState = { count: 0 };

type ACTIONTYPE =
  | { type: "increment"; payload: number }
  | { type: "decrement"; payload: string };

function reducer(state: typeof initialState, action: ACTIONTYPE) {
  switch (action.type) {
    case "increment":
      return { count: state.count + action.payload };
    case "decrement":
      return { count: state.count - Number(action.payload) };
    default:
      throw new Error();
  }
}

function Counter() {
  const [state, dispatch] = React.useReducer(reducer, initialState);
  return (
    <>
      Count: {state.count}
      <button onClick={() => dispatch({ type: "decrement", payload: "5" })}>
        -
      </button>
      <button onClick={() => dispatch({ type: "increment", payload: 5 })}>
        +
      </button>
    </>
  );
}

View in the TypeScript Playground

import { Reducer } from 'redux';

export function reducer: Reducer<AppState, Action>() {}

useEffect #

When using useEffect, take care not to return anything other than a function or undefined, otherwise both TypeScript and React will yell at you. This can be subtle when using arrow functions:

function DelayedEffect(props: { timerMs: number }) {
  const { timerMs } = props;

  useEffect(
    () =>
      setTimeout(() => {
        /* do stuff */
      }, timerMs),
    [timerMs]
  );
  // bad example! setTimeout implicitly returns a number
  // because the arrow function body isn't wrapped in curly braces
  return null;
}

function DelayedEffect(props: { timerMs: number }) {
  const { timerMs } = props;

  useEffect(() => {
    setTimeout(() => {
      /* do stuff */
    }, timerMs);
  }, [timerMs]);
  // better; use the void keyword to make sure you return undefined
  return null;
}

useRef #

When using useRef, you have two options when creating a ref container that does not have an initial value:

const ref1 = useRef<HTMLElement>(null!);
const ref2 = useRef<HTMLElement>(null);
const ref3 = useRef<HTMLElement | null>(null);

You can see the difference in this playground, thanks to this discussion with @rajivpunjabi.

The first option will bypass nullchecks on ref1.current, and is intended to be passed in to built-in ref attributes that React will manage (because React handles setting the current value for you).

function MyComponent() {
  const ref1 = useRef<HTMLDivElement>(null!);
  useEffect(() => {
    doSomethingWith(ref1.current);
    // TypeScript won't require null-check e.g. ref1 && ref1.current
  });
  return <div ref={ref1}> etc </div>;
}

The second option will infer a RefObject instead of a MutableRefObject. This means there will be a type error if you try to assign to ref2.current.

The third option will make ref3.current mutable, and is intended for "instance variables" that you manage yourself.

function TextInputWithFocusButton() {
  // initialise with null, but tell TypeScript we are looking for an HTMLInputElement
  const inputEl = React.useRef<HTMLInputElement>(null);
  const onButtonClick = () => {
    // strict null checks need us to check if inputEl and current exist.
    // but once current exists, it is of type HTMLInputElement, thus it
    // has the method focus! ✅
    if (inputEl && inputEl.current) {
      inputEl.current.focus();
    }
  };
  return (
    <>
      {/* in addition, inputEl only can be used with input elements. Yay! */}
      <input ref={inputEl} type="text" />
      <button onClick={onButtonClick}>Focus the input</button>
    </>
  );
}

View in the TypeScript Playground

example from Stefan Baumgartner

useImperativeHandle #

we dont have much here, but this is from a discussion in our issues. Please contribute if you have anything to add!

type ListProps<ItemType> = {
  items: ItemType[];
  innerRef?: React.Ref<{ scrollToItem(item: ItemType): void }>;
};

function List<ItemType>(props: ListProps<ItemType>) {
  useImperativeHandle(props.innerRef, () => ({
    scrollToItem() {},
  }));
  return null;
}

Custom Hooks #

If you are returning an array in your Custom Hook, you will want to avoid type inference as TypeScript will infer a union type (when you actually want different types in each position of the array). Instead, use TS 3.4 const assertions:

export function useLoading() {
  const [isLoading, setState] = React.useState(false);
  const load = (aPromise: Promise<any>) => {
    setState(true);
    return aPromise.finally(() => setState(false));
  };
  return [isLoading, load] as const; // infers [boolean, typeof load] instead of (boolean | typeof load)[]
}

View in the TypeScript Playground

This way, when you destructure you actually get the right types based on destructure position.

export function useLoading() {
  const [isLoading, setState] = React.useState(false);
  const load = (aPromise: Promise<any>) => {
    setState(true);
    return aPromise.finally(() => setState(false));
  };
  return [isLoading, load] as [
    boolean,
    (aPromise: Promise<any>) => Promise<any>
  ];
}

function tuplify<T extends any[]>(...elements: T) {
  return elements;
}

function useArray() {
  const numberValue = useRef(3).current;
  const functionValue = useRef(() => {}).current;
  return [numberValue, functionValue]; // type is (number | (() => void))[]
}

function useTuple() {
  const numberValue = useRef(3).current;
  const functionValue = useRef(() => {}).current;
  return tuplify(numberValue, functionValue); // type is [number, () => void]
}

Note that the React team recommends that custom hooks that return more than two values should use proper objects instead of tuples, however.

More Hooks + TypeScript reading: #

• https://medium.com/@jrwebdev/react-hooks-in-typescript-88fce7001d0d
• https://fettblog.eu/typescript-react/hooks/#useref

If you are writing a React Hooks library, don't forget that you should also expose your types for users to use.

Example React Hooks + TypeScript Libraries: #

• https://github.com/mweststrate/use-st8
• https://github.com/palmerhq/the-platform
• https://github.com/sw-yx/hooks

Something to add? File an issue.

Class Components #

Within TypeScript, React.Component is a generic type (aka React.Component<PropType, StateType>), so you want to provide it with (optional) prop and state type parameters:

type MyProps = {
  // using `interface` is also ok
  message: string;
};
type MyState = {
  count: number; // like this
};
class App extends React.Component<MyProps, MyState> {
  state: MyState = {
    // optional second annotation for better type inference
    count: 0,
  };
  render() {
    return (
      <div>
        {this.props.message} {this.state.count}
      </div>
    );
  }
}

View in the TypeScript Playground

Don't forget that you can export/import/extend these types/interfaces for reuse.

type MyProps = {
  readonly message: string;
};
type MyState = {
  readonly count: number;
};

Class Methods: Do it like normal, but just remember any arguments for your functions also need to be typed:

class App extends React.Component<{ message: string }, { count: number }> {
  state = { count: 0 };
  render() {
    return (
      <div onClick={() => this.increment(1)}>
        {this.props.message} {this.state.count}
      </div>
    );
  }
  increment = (amt: number) => {
    // like this
    this.setState((state) => ({
      count: state.count + amt,
    }));
  };
}

View in the TypeScript Playground

Class Properties: If you need to declare class properties for later use, just declare it like state, but without assignment:

class App extends React.Component<{
  message: string;
}> {
  pointer: number; // like this
  componentDidMount() {
    this.pointer = 3;
  }
  render() {
    return (
      <div>
        {this.props.message} and {this.pointer}
      </div>
    );
  }
}

View in the TypeScript Playground

Something to add? File an issue.

Typing getDerivedStateFromProps #

Before you start using getDerivedStateFromProps, please go through the documentation and You Probably Don't Need Derived State. Derived State can be implemented using hooks which can also help set up memoization.

Here are a few ways in which you can annotate getDerivedStateFromProps

1. If you have explicitly typed your derived state and want to make sure that the return value from getDerivedStateFromProps conforms to it.

class Comp extends React.Component<Props, State> {
  static getDerivedStateFromProps(
    props: Props,
    state: State
  ): Partial<State> | null {
    //
  }
}

2. When you want the function's return value to determine your state.

class Comp extends React.Component<
  Props,
  ReturnType<typeof Comp["getDerivedStateFromProps"]>
> {
  static getDerivedStateFromProps(props: Props) {}
}

3. When you want derived state with other state fields and memoization

type CustomValue = any;
interface Props {
  propA: CustomValue;
}
interface DefinedState {
  otherStateField: string;
}
type State = DefinedState & ReturnType<typeof transformPropsToState>;
function transformPropsToState(props: Props) {
  return {
    savedPropA: props.propA, // save for memoization
    derivedState: props.propA,
  };
}
class Comp extends React.PureComponent<Props, State> {
  constructor(props: Props) {
    super(props);
    this.state = {
      otherStateField: "123",
      ...transformPropsToState(props),
    };
  }
  static getDerivedStateFromProps(props: Props, state: State) {
    if (isEqual(props.propA, state.savedPropA)) return null;
    return transformPropsToState(props);
  }
}

View in the TypeScript Playground

You May Not Need defaultProps #

As per this tweet, defaultProps will eventually be deprecated. You can check the discussions here:

• https://twitter.com/hswolff/status/1133759319571345408

The consensus is to use object default values.

Function Components:

type GreetProps = { age?: number };

const Greet = ({ age = 21 }: GreetProps) => // etc

Class Components:

type GreetProps = {
  age?: number;
};

class Greet extends React.Component<GreetProps> {
  render() {
    const { age = 21 } = this.props;
    /*...*/
  }
}

let el = <Greet age={3} />;

Typing defaultProps #

Type inference improved greatly for defaultProps in TypeScript 3.0+, although some edge cases are still problematic.

Function Components

type GreetProps = { age: number } & typeof defaultProps;
const defaultProps = {
  age: 21,
};

const Greet = (props: GreetProps) => {
  // etc
};
Greet.defaultProps = defaultProps;

See this in TS Playground

For Class components, there are a couple ways to do it(including using the Pick utility type) but the recommendation is to "reverse" the props definition:

type GreetProps = typeof Greet.defaultProps & {
  age: number;
};

class Greet extends React.Component<GreetProps> {
  static defaultProps = {
    age: 21,
  };
  /*...*/
}

// Type-checks! No type assertions needed!
let el = <Greet age={3} />;

// internal contract, should not be exported out
type GreetProps = {
  age?: number;
};

class Greet extends Component<GreetProps> {
  static defaultProps = { age: 21 };
}

// external contract
export type ApparentGreetProps = JSX.LibraryManagedAttributes<
  typeof Greet,
  GreetProps
>;

Consuming Props of a Component with defaultProps #

A component with defaultProps may seem to have some required props that actually aren't.

Problem Statement #

Here's what you want to do:

interface IProps {
  name: string;
}
const defaultProps = {
  age: 25,
};
const GreetComponent = ({ name, age }: IProps & typeof defaultProps) => (
  <div>{`Hello, my name is ${name}, ${age}`}</div>
);
GreetComponent.defaultProps = defaultProps;

const TestComponent = (props: React.ComponentProps<typeof GreetComponent>) => {
  return <h1 />;
};

// Property 'age' is missing in type '{ name: string; }' but required in type '{ age: number; }'
const el = <TestComponent name="foo" />;

Solution #

Define a utility that applies JSX.LibraryManagedAttributes:

type ComponentProps<T> = T extends
  | React.ComponentType<infer P>
  | React.Component<infer P>
  ? JSX.LibraryManagedAttributes<T, P>
  : never;

const TestComponent = (props: ComponentProps<typeof GreetComponent>) => {
  return <h1 />;
};

// No error
const el = <TestComponent name="foo" />;

See this in TS Playground

Misc Discussions and Knowledge #

type Props = Required<typeof MyComponent.defaultProps> & {
  /* additional props here */
};

export class MyComponent extends React.Component<Props> {
  static defaultProps = {
    foo: "foo",
  };
}

interface IMyComponentProps {
  firstProp?: string;
  secondProp: IPerson[];
}

export class MyComponent extends React.Component<IMyComponentProps> {
  public static defaultProps: Partial<IMyComponentProps> = {
    firstProp: "default",
  };
}

Something to add? File an issue.

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";
  /** any object as long as you dont use its properties (NOT COMMON but useful as placeholder) */
  obj: object;
  obj2: {}; // almost the same as `object`, exactly the same as `Object`
  /** an object with any number of properties (PREFERRED) */
  obj3: {
    id: string;
    title: string;
  };
  /** array of objects! (common) */
  objArr: {
    id: string;
    title: string;
  }[];
  /** a dict object with any number of properties of the same type */
  dict1: {
    [key: string]: MyTypeHere;
  };
  dict2: Record<string, MyTypeHere>; // equivalent to dict1
  /** any function as long as you don't invoke it (not recommended) */
  onSomething: Function;
  /** function that doesn't take or return anything (VERY COMMON) */
  onClick: () => void;
  /** function with named prop (VERY COMMON) */
  onChange: (id: number) => void;
  /** alternative function type syntax that takes an event (VERY COMMON) */
  onClick(event: React.MouseEvent<HTMLButtonElement>): void;
  /** an optional prop (VERY COMMON!) */
  optional?: OptionalType;
};

Notice we have used the TSDoc /** comment */ style here on each prop. You can and are encouraged to leave descriptive comments on reusable components. For a fuller example and discussion, see our Commenting Components section in the Advanced Cheatsheet.

Useful React Prop Type Examples #

Relevant for components that accept other React components as props.

export declare interface AppProps {
  children1: JSX.Element; // bad, doesnt account for arrays
  children2: JSX.Element | JSX.Element[]; // meh, doesn't accept strings
  children3: React.ReactChildren; // despite the name, not at all an appropriate type; it is a utility
  children4: React.ReactChild[]; // better, accepts array children
  children: React.ReactNode; // best, accepts everything (see edge case below)
  functionChildren: (name: string) => React.ReactNode; // recommended function as a child render prop type
  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
}

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

function Comp({ children }: Props) {
  return <div>{children}</div>;
}
function App() {
  return <Comp>{{}}</Comp>; // Runtime Error: Objects not valid as React Child!
}

More discussion: Where ReactNode does not overlap with 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:

⚠️ In some cases

(source: Karol Majewski)

Something to add? File an issue.

getDerivedStateFromProps #

Before you start using getDerivedStateFromProps, please go through the documentation and You Probably Don't Need Derived State. Derived State can be easily achieved using hooks which can also help set up memoization easily.

Here are a few ways in which you can annotate getDerivedStateFromProps

1. If you have explicitly typed your derived state and want to make sure that the return value from getDerivedStateFromProps conforms to it.

class Comp extends React.Component<Props, State> {
  static getDerivedStateFromProps(
    props: Props,
    state: State
  ): Partial<State> | null {
    //
  }
}

2. When you want the function's return value to determine your state.

class Comp extends React.Component<
  Props,
  ReturnType<typeof Comp["getDerivedStateFromProps"]>
> {
  static getDerivedStateFromProps(props: Props) {}
}

3. When you want derived state with other state fields and memoization

type CustomValue = any;
interface Props {
  propA: CustomValue;
}
interface DefinedState {
  otherStateField: string;
}
type State = DefinedState & ReturnType<typeof transformPropsToState>;
function transformPropsToState(props: Props) {
  return {
    savedPropA: props.propA, // save for memoization
    derivedState: props.propA,
  };
}
class Comp extends React.PureComponent<Props, State> {
  constructor(props: Props) {
    super(props);
    this.state = {
      otherStateField: "123",
      ...transformPropsToState(props),
    };
  }
  static getDerivedStateFromProps(props: Props, state: State) {
    if (isEqual(props.propA, state.savedPropA)) return null;
    return transformPropsToState(props);
  }
}

View in the TypeScript Playground

Forms and Events #

If performance is not an issue (and it usually isn't!), inlining handlers is easiest as you can just use type inference and contextual typing:

const el = (
  <button
    onClick={(event) => {
      /* event will be correctly typed automatically! */
    }}
  />
);

But if you need to define your event handler separately, IDE tooling really comes in handy here, as the @type definitions come with a wealth of typing. Type what you are looking for and usually the autocomplete will help you out. Here is what it looks like for an onChange for a form event:

type State = {
  text: string;
};
class App extends React.Component<Props, State> {
  state = {
    text: "",
  };

  // typing on RIGHT hand side of =
  onChange = (e: React.FormEvent<HTMLInputElement>): void => {
    this.setState({ text: e.currentTarget.value });
  };
  render() {
    return (
      <div>
        <input type="text" value={this.state.text} onChange={this.onChange} />
      </div>
    );
  }
}

View in the TypeScript Playground

Instead of typing the arguments and return values with React.FormEvent<> and void, you may alternatively apply types to the event handler itself (contributed by @TomasHubelbauer):

  // typing on LEFT hand side of =
  onChange: React.ChangeEventHandler<HTMLInputElement> = (e) => {
    this.setState({text: e.currentTarget.value})
  }

Typing onSubmit, with Uncontrolled components in a Form

If you don't quite care about the type of the event, you can just use React.SyntheticEvent. If your target form has custom named inputs that you'd like to access, you can use type widening:

<form
  ref={formRef}
  onSubmit={(e: React.SyntheticEvent) => {
    e.preventDefault();
    const target = e.target as typeof e.target & {
      email: { value: string };
      password: { value: string };
    };
    const email = target.email.value; // typechecks!
    const password = target.password.value; // typechecks!
    // etc...
  }}
>
  <div>
    <label>
      Email:
      <input type="email" name="email" />
    </label>
  </div>
  <div>
    <label>
      Password:
      <input type="password" name="password" />
    </label>
  </div>
  <div>
    <input type="submit" value="Log in" />
  </div>
</form>

View in the TypeScript Playground

Of course, if you're making any sort of significant form, you should use Formik or React Hook Form, which are written in TypeScript.

Context #

Basic Example #

import * as React from "react";

interface AppContextInterface {
  name: string;
  author: string;
  url: string;
}

const AppCtx = React.createContext<AppContextInterface | null>(null);

// Provider in your app

const sampleAppContext: AppContextInterface = {
  name: "Using React Context in a Typescript App",
  author: "thehappybug",
  url: "http://www.example.com",
};

export const App = () => (
  <AppCtx.Provider value={sampleAppContext}>...</AppCtx.Provider>
);

// Consume in your app

export const PostInfo = () => {
  const appContext = React.useContext(AppCtx);
  return (
    <div>
      Name: {appContext.name}, Author: {appContext.author}, Url:{" "}
      {appContext.url}
    </div>
  );
};

You can also use the Class.contextType or Context.Consumer API, let us know if you have trouble with that.

Thanks to @AlvSovereign

Extended Example #

Using React.createContext with an empty object as default value.

interface ContextState {
  // set the type of state you want to handle with context e.g.
  name: string | null;
}
//set an empty object as default state
const Context = React.createContext({} as ContextState);
// set up context provider as you normally would in JavaScript [React Context API](https://reactjs.org/docs/context.html#api)

Using React.createContext and context getters to make a createCtx with no defaultValue, yet no need to check for undefined:

import * as React from "react";

const currentUserContext = React.createContext<string | undefined>(undefined);

function EnthusasticGreeting() {
  const currentUser = React.useContext(currentUserContext);
  return <div>HELLO {currentUser!.toUpperCase()}!</div>;
}

function App() {
  return (
    <currentUserContext.Provider value="Anders">
      <EnthusasticGreeting />
    </currentUserContext.Provider>
  );
}

Notice the explicit type arguments which we need because we don't have a default string value:

const currentUserContext = React.createContext<string | undefined>(undefined);
//                                             ^^^^^^^^^^^^^^^^^^

along with the non-null assertion to tell TypeScript that currentUser is definitely going to be there:

return <div>HELLO {currentUser!.toUpperCase()}!</div>;
//                              ^

This is unfortunate because we know that later in our app, a Provider is going to fill in the context.

There are a few solutions for this:

1. You can get around this by asserting non null:

   const currentUserContext = React.createContext<string>(undefined!);
   

   (Playground here) This is a quick and easy fix, but this loses type-safety, and if you forget to supply a value to the Provider, you will get an error.

2. We can write a helper function called createCtx that guards against accessing a Context whose value wasn't provided. By doing this, API instead, we never have to provide a default and never have to check for undefined:

   import * as React from "react";
   
   /**
    * A helper to create a Context and Provider with no upfront default value, and
    * without having to check for undefined all the time.
    */
   function createCtx<A extends {} | null>() {
     const ctx = React.createContext<A | undefined>(undefined);
     function useCtx() {
       const c = React.useContext(ctx);
       if (c === undefined)
         throw new Error("useCtx must be inside a Provider with a value");
       return c;
     }
     return [useCtx, ctx.Provider] as const; // 'as const' makes TypeScript infer a tuple
   }
   
   // Usage:
   
   // We still have to specify a type, but no default!
   export const [useCurrentUserName, CurrentUserProvider] = createCtx<string>();
   
   function EnthusasticGreeting() {
     const currentUser = useCurrentUserName();
     return <div>HELLO {currentUser.toUpperCase()}!</div>;
   }
   
   function App() {
     return (
       <CurrentUserProvider value="Anders">
         <EnthusasticGreeting />
       </CurrentUserProvider>
     );
   }
   

   View in the TypeScript Playground

3. You can go even further and combine this idea using React.createContext and context getters.

   /**
    * A helper to create a Context and Provider with no upfront default value, and
    * without having to check for undefined all the time.
    */
   function createCtx<A extends {} | null>() {
     const ctx = React.createContext<A | undefined>(undefined);
     function useCtx() {
       const c = React.useContext(ctx);
       if (c === undefined)
         throw new Error("useCtx must be inside a Provider with a value");
       return c;
     }
     return [useCtx, ctx.Provider] as const; // 'as const' makes TypeScript infer a tuple
   }
   
   // usage
   
   export const [useCtx, SettingProvider] = createCtx<string>(); // specify type, but no need to specify value upfront!
   export function App() {
     const key = useCustomHook("key"); // get a value from a hook, must be in a component
     return (
       <SettingProvider value={key}>
         <Component />
       </SettingProvider>
     );
   }
   export function Component() {
     const key = useCtx(); // can still use without null check!
     return <div>{key}</div>;
   }
   

   View in the TypeScript Playground

4. Using React.createContext and useContext to make a createCtx with unstated-like context setters:

   export function createCtx<A>(defaultValue: A) {
     type UpdateType = React.Dispatch<
       React.SetStateAction<typeof defaultValue>
     >;
     const defaultUpdate: UpdateType = () => defaultValue;
     const ctx = React.createContext({
       state: defaultValue,
       update: defaultUpdate,
     });
     function Provider(props: React.PropsWithChildren<{}>) {
       const [state, update] = React.useState(defaultValue);
       return <ctx.Provider value={{ state, update }} {...props} />;
     }
     return [ctx, Provider] as const; // alternatively, [typeof ctx, typeof Provider]
   }
   
   // usage
   
   const [ctx, TextProvider] = createCtx("someText");
   export const TextContext = ctx;
   export function App() {
     return (
       <TextProvider>
         <Component />
       </TextProvider>
     );
   }
   export function Component() {
     const { state, update } = React.useContext(TextContext);
     return (
       <label>
         {state}
         <input type="text" onChange={(e) => update(e.target.value)} />
       </label>
     );
   }
   

   View in the TypeScript Playground

5. A useReducer-based version may also be helpful.

interface ProviderState {
  themeColor: string;
}

interface UpdateStateArg {
  key: keyof ProviderState;
  value: string;
}

interface ProviderStore {
  state: ProviderState;
  update: (arg: UpdateStateArg) => void;
}

const Context = React.createContext({} as ProviderStore); // type assertion on empty object

class Provider extends React.Component<{}, ProviderState> {
  public readonly state = {
    themeColor: "red",
  };

  private update = ({ key, value }: UpdateStateArg) => {
    this.setState({ [key]: value });
  };

  public render() {
    const store: ProviderStore = {
      state: this.state,
      update: this.update,
    };

    return (
      <Context.Provider value={store}>{this.props.children}</Context.Provider>
    );
  }
}

const Consumer = Context.Consumer;

Something to add? File an issue.

forwardRef/createRef #

Check the Hooks section for useRef.

createRef:

class CssThemeProvider extends React.PureComponent<Props> {
  private rootRef = React.createRef<HTMLDivElement>(); // like this
  render() {
    return <div ref={this.rootRef}>{this.props.children}</div>;
  }
}

forwardRef:

type Props = { children: React.ReactNode; type: "submit" | "button" };
export type Ref = HTMLButtonElement;
export const FancyButton = React.forwardRef<Ref, Props>((props, ref) => (
  <button ref={ref} className="MyClassName" type={props.type}>
    {props.children}
  </button>
));

type Props = { children: React.ReactNode; type: "submit" | "button" };
export type Ref = HTMLButtonElement;
export const FancyButton = React.forwardRef((
  props: Props,
  ref: React.Ref<Ref> // <-- here!
) => (
  <button ref={ref} className="MyClassName" type={props.type}>
    {props.children}
  </button>
));

If you are grabbing the props of a component that forwards refs, use ComponentPropsWithRef.

More info: https://medium.com/@martin_hotell/react-refs-with-typescript-a32d56c4d315

You may also wish to do Conditional Rendering with forwardRef.

Something to add? File an issue.

Portals #

Using ReactDOM.createPortal:

const modalRoot = document.getElementById("modal-root") as HTMLElement;
// assuming in your html file has a div with id 'modal-root';

export class Modal extends React.Component {
  el: HTMLElement = document.createElement("div");

  componentDidMount() {
    modalRoot.appendChild(this.el);
  }

  componentWillUnmount() {
    modalRoot.removeChild(this.el);
  }

  render() {
    return ReactDOM.createPortal(this.props.children, this.el);
  }
}

View in the TypeScript Playground

import React, { useEffect, useRef } from "react";
import { createPortal } from "react-dom";

const modalRoot = document.querySelector("#modal-root") as HTMLElement;

const Modal: React.FC<{}> = ({ children }) => {
  const el = useRef(document.createElement("div"));

  useEffect(() => {
    // Use this in case CRA throws an error about react-hooks/exhaustive-deps
    const current = el.current;

    // We assume `modalRoot` exists with '!'
    modalRoot!.appendChild(current);
    return () => void modalRoot!.removeChild(current);
  }, []);

  return createPortal(children, el.current);
};

export default Modal;

Modal Component Usage Example:

function App() {
  const [showModal, setShowModal] = React.useState(false);
  return (
    <div>
      // you can also put this in your static html file
      <div id="modal-root"></div>
      {showModal && (
        <Modal>
          <div
            style={{
              display: "grid",
              placeItems: "center",
              height: "100vh",
              width: "100vh",
              background: "rgba(0,0,0,0.1)",
              zIndex: 99,
            }}
          >
            I'm a modal!{" "}
            <button
              style={{ background: "papyawhip" }}
              onClick={() => setShowModal(false)}
            >
              close
            </button>
          </div>
        </Modal>
      )}
      <button onClick={() => setShowModal(true)}>show Modal</button>
      // rest of your app
    </div>
  );
}

Error Boundaries #

Option 1: Using react-error-boundary #

React-error-boundary - is a lightweight package ready to use for this scenario with TS support built-in. This approach also lets you avoid class components that are not that popular anymore.

Options 2: Writing your custom error boundary component #

If you don't want to add a new npm package for this, you can also write your own ErrorBoundary component.

import React, { Component, ErrorInfo, ReactNode } from "react";

interface Props {
  children: ReactNode;
}

interface State {
  hasError: boolean;
}

class ErrorBoundary extends Component<Props, State> {
  public state: State = {
    hasError: false
  };

  public static getDerivedStateFromError(_: Error): State {
    // Update state so the next render will show the fallback UI.
    return { hasError: true };
  }

  public componentDidCatch(error: Error, errorInfo: ErrorInfo) {
    console.error("Uncaught error:", error, errorInfo);
  }

  public render() {
    if (this.state.hasError) {
      return <h1>Sorry.. there was an error</h1>;
    }

    return this.props.children;
  }
}

export default ErrorBoundary;

Something to add? File an issue.

Concurrent React/React Suspense #

Not written yet. watch https://github.com/sw-yx/fresh-async-react for more on React Suspense and Time Slicing.

Something to add? File an issue.

Troubleshooting Handbook: Types #

⚠️ Have you read the TypeScript FAQ Your answer might be there!

Facing weird type errors? You aren't alone. This is the hardest part of using TypeScript with React. Be patient - you are learning a new language after all. However, the more you get good at this, the less time you'll be working against the compiler and the more the compiler will be working for you!

Try to avoid typing with any as much as possible to experience the full benefits of TypeScript. Instead, let's try to be familiar with some of the common strategies to solve these issues.

Union Types and Type Guarding #

Union types are handy for solving some of these typing problems:

class App extends React.Component<
  {},
  {
    count: number | null; // like this
  }
> {
  state = {
    count: null,
  };
  render() {
    return <div onClick={() => this.increment(1)}>{this.state.count}</div>;
  }
  increment = (amt: number) => {
    this.setState((state) => ({
      count: (state.count || 0) + amt,
    }));
  };
}

View in the TypeScript Playground

Type Guarding: Sometimes Union Types solve a problem in one area but create another downstream. If A and B are both object types, A | B isn't "either A or B", it is "A or B or both at once", which causes some confusion if you expected it to be the former. Learn how to write checks, guards, and assertions (also see the Conditional Rendering section below). For example:

interface Admin {
  role: string;
}
interface User {
  email: string;
}

// Method 1: use `in` keyword
function redirect(user: Admin | User) {
  if ("role" in user) {
    // use the `in` operator for typeguards since TS 2.7+
    routeToAdminPage(user.role);
  } else {
    routeToHomePage(user.email);
  }
}

// Method 2: custom type guard, does the same thing in older TS versions or where `in` isnt enough
function isAdmin(user: Admin | User): user is Admin {
  return (user as any).role !== undefined;
}

View in the TypeScript Playground

Method 2 is also known as User-Defined Type Guards and can be really handy for readable code. This is how TS itself refines types with typeof and instanceof.

If you need if...else chains or the switch statement instead, it should "just work", but look up Discriminated Unions if you need help. (See also: Basarat's writeup). This is handy in typing reducers for useReducer or Redux.

Optional Types #

If a component has an optional prop, add a question mark and assign during destructure (or use defaultProps).

class MyComponent extends React.Component<{
  message?: string; // like this
}> {
  render() {
    const { message = "default" } = this.props;
    return <div>{message}</div>;
  }
}

You can also use a ! character to assert that something is not undefined, but this is not encouraged.

Something to add? File an issue with your suggestions!

Enum Types #

We recommend avoiding using enums as far as possible.

Enums have a few documented issues (the TS team agrees). A simpler alternative to enums is just declaring a union type of string literals:

export declare type Position = "left" | "right" | "top" | "bottom";

If you must use enums, remember that enums in TypeScript default to numbers. You will usually want to use them as strings instead:

export enum ButtonSizes {
  default = "default",
  small = "small",
  large = "large",
}

// usage
export const PrimaryButton = (
  props: Props & React.HTMLProps<HTMLButtonElement>
) => <Button size={ButtonSizes.default} {...props} />;

Type Assertion #

Sometimes you know better than TypeScript that the type you're using is narrower than it thinks, or union types need to be asserted to a more specific type to work with other APIs, so assert with the as keyword. This tells the compiler you know better than it does.

class MyComponent extends React.Component<{
  message: string;
}> {
  render() {
    const { message } = this.props;
    return (
      <Component2 message={message as SpecialMessageType}>{message}</Component2>
    );
  }
}

View in the TypeScript Playground

Note that you cannot assert your way to anything - basically it is only for refining types. Therefore it is not the same as "casting" a type.

You can also assert a property is non-null, when accessing it:

element.parentNode!.removeChild(element) // ! before the period
myFunction(document.getElementById(dialog.id!)! // ! after the property accessing
let userID!: string // definite assignment assertion... be careful!

Of course, try to actually handle the null case instead of asserting :)

Simulating Nominal Types #

TS' structural typing is handy, until it is inconvenient. However you can simulate nominal typing with type branding:

type OrderID = string & { readonly brand: unique symbol };
type UserID = string & { readonly brand: unique symbol };
type ID = OrderID | UserID;

We can create these values with the Companion Object Pattern:

function OrderID(id: string) {
  return id as OrderID;
}
function UserID(id: string) {
  return id as UserID;
}

Now TypeScript will disallow you from using the wrong ID in the wrong place:

function queryForUser(id: UserID) {
  // ...
}
queryForUser(OrderID("foobar")); // Error, Argument of type 'OrderID' is not assignable to parameter of type 'UserID'

In future you can use the unique keyword to brand. See this PR.

Intersection Types #

Adding two types together can be handy, for example when your component is supposed to mirror the props of a native component like a button:

export interface PrimaryButtonProps {
  label: string;
}
export const PrimaryButton = (
  props: PrimaryButtonProps & React.ButtonHTMLAttributes<HTMLButtonElement>
) => {
  // do custom buttony stuff
  return <button {...props}> {props.label} </button>;
};

Playground here

You can also use Intersection Types to make reusable subsets of props for similar components:

type BaseProps = {
   className?: string,
   style?: React.CSSProperties
   name: string // used in both
}
type DogProps = {
  tailsCount: number
}
type HumanProps = {
  handsCount: number
}
export const Human: React.FC<BaseProps & HumanProps> = // ...
export const Dog: React.FC<BaseProps & DogProps> = // ...

View in the TypeScript Playground

Make sure not to confuse Intersection Types (which are and operations) with Union Types (which are or operations).

Union Types #

This section is yet to be written (please contribute!). Meanwhile, see our commentary on Union Types usecases.

The ADVANCED cheatsheet also has information on Discriminated Union Types, which are helpful when TypeScript doesn't seem to be narrowing your union type as you expect.

Overloading Function Types #

Specifically when it comes to functions, you may need to overload instead of union type. The most common way function types are written uses the shorthand:

type FunctionType1 = (x: string, y: number) => number;

But this doesn't let you do any overloading. If you have the implementation, you can put them after each other with the function keyword:

function pickCard(x: { suit: string; card: number }[]): number;
function pickCard(x: number): { suit: string; card: number };
function pickCard(x): any {
  // implementation with combined signature
  // ...
}

However, if you don't have an implementation and are just writing a .d.ts definition file, this won't help you either. In this case you can forego any shorthand and write them the old-school way. The key thing to remember here is as far as TypeScript is concerned, functions are just callable objects with no key:

type pickCard = {
  (x: { suit: string; card: number }[]): number;
  (x: number): { suit: string; card: number };
  // no need for combined signature in this form
  // you can also type static properties of functions here eg `pickCard.wasCalled`
};

Note that when you implement the actual overloaded function, the implementation will need to declare the combined call signature that you'll be handling, it won't be inferred for you. You can see readily see examples of overloads in DOM APIs, e.g. createElement.

Read more about Overloading in the Handbook.

Using Inferred Types #

Leaning on TypeScript's Type Inference is great... until you realize you need a type that was inferred, and have to go back and explicitly declare types/interfaces so you can export them for reuse.

Fortunately, with typeof, you won't have to do that. Just use it on any value:

const [state, setState] = React.useState({
  foo: 1,
  bar: 2,
}); // state's type inferred to be {foo: number, bar: number}

const someMethod = (obj: typeof state) => {
  // grabbing the type of state even though it was inferred
  // some code using obj
  setState(obj); // this works
};

Using Partial Types #

Working with slicing state and props is common in React. Again, you don't really have to go and explicitly redefine your types if you use the Partial generic type:

const [state, setState] = React.useState({
  foo: 1,
  bar: 2,
}); // state's type inferred to be {foo: number, bar: number}

// NOTE: stale state merging is not actually encouraged in React.useState
// we are just demonstrating how to use Partial here
const partialStateUpdate = (obj: Partial<typeof state>) =>
  setState({ ...state, ...obj });

// later on...
partialStateUpdate({ foo: 2 }); // this works

The Types I need weren't exported! #

This can be annoying but here are ways to grab the types!

• Grabbing the Prop types of a component: Use React.ComponentProps and typeof, and optionally Omit any overlapping types

import { Button } from "library"; // but doesn't export ButtonProps! oh no!
type ButtonProps = React.ComponentProps<typeof Button>; // no problem! grab your own!
type AlertButtonProps = Omit<ButtonProps, "onClick">; // modify
const AlertButton: React.FC<AlertButtonProps> = (props) => (
  <Button onClick={() => alert("hello")} {...props} />
);

You may also use ComponentPropsWithoutRef (instead of ComponentProps) and ComponentPropsWithRef (if your component specifically forwards refs)

• Grabbing the return type of a function: use ReturnType:

// inside some library - return type { baz: number } is inferred but not exported
function foo(bar: string) {
  return { baz: 1 };
}

//  inside your app, if you need { baz: number }
type FooReturn = ReturnType<typeof foo>; // { baz: number }

In fact you can grab virtually anything public: see this blogpost from Ivan Koshelev

function foo() {
  return {
    a: 1,
    b: 2,
    subInstArr: [
      {
        c: 3,
        d: 4,
      },
    ],
  };
}

type InstType = ReturnType<typeof foo>;
type SubInstArr = InstType["subInstArr"];
type SubIsntType = SubInstArr[0];

let baz: SubIsntType = {
  c: 5,
  d: 6, // type checks ok!
};

//You could just write a one-liner,
//But please make sure it is forward-readable
//(you can understand it from reading once left-to-right with no jumps)
type SubIsntType2 = ReturnType<typeof foo>["subInstArr"][0];
let baz2: SubIsntType2 = {
  c: 5,
  d: 6, // type checks ok!
};

• TS also ships with a Parameters utility type for extracting the parameters of a function
• for anything more "custom", the infer keyword is the basic building block for this, but takes a bit of getting used to. Look at the source code for the above utility types, and this example to get the idea. Basarat also has a good video on infer.

The Types I need don't exist! #

What's more annoying than modules with unexported types? Modules that are untyped!

Before you proceed - make sure you have checked that types don't exist in DefinitelyTyped or TypeSearch

Fret not! There are more than a couple of ways in which you can solve this problem.

Slapping any on everything #

A lazier way would be to create a new type declaration file, say typedec.d.ts– if you don't already have one. Ensure that the path to file is resolvable by TypeScript by checking the include array in the tsconfig.json file at the root of your directory.

// inside tsconfig.json
{
  // ...
  "include": [
    "src" // automatically resolves if the path to declaration is src/typedec.d.ts
  ]
  // ...
}

Within this file, add the declare syntax for your desired module, say my-untyped-module– to the declaration file:

// inside typedec.d.ts
declare module "my-untyped-module";

This one-liner alone is enough if you just need it to work without errors. A even hackier, write-once-and-forget way would be to use "*" instead which would then apply the Any type for all existing and future untyped modules.

This solution works well as a workaround if you have less than a couple untyped modules. Anything more, you now have a ticking type-bomb in your hands. The only way of circumventing this problem would be to define the missing types for those untyped modules as explained in the following sections.

Autogenerate types #

You can use TypeScript with --allowJs and --declaration to see TypeScript's "best guess" at the types of the library.

If this doesn't work well enough, use dts-gen to use the runtime shape of the object to accurately enumerate all available properties. This tends to be very accurate, BUT the tool does not yet support scraping JSDoc comments to populate additional types.

npm install -g dts-gen
dts-gen -m <your-module>

There are other automated JS to TS conversion tools and migration strategies - see our MIGRATION cheatsheet.

Typing Exported Hooks #

Typing Hooks is just like typing pure functions.

The following steps work under two assumptions:

• You have already created a type declaration file as stated earlier in the section.
• You have access to the source code - specifically the code that directly exports the functions you will be using. In most cases, it would be housed in an index.js file. Typically you need a minimum of two type declarations (one for Input Prop and the other for Return Prop) to define a hook completely. Suppose the hook you wish to type follows the following structure,

// ...
const useUntypedHook = (prop) => {
  // some processing happens here
  return {
    /* ReturnProps */
  };
};
export default useUntypedHook;

then, your type declaration should most likely follow the following syntax.

declare module 'use-untyped-hook' {
  export interface InputProps { ... }   // type declaration for prop
  export interface ReturnProps { ... } // type declaration for return props
  export default function useUntypedHook(
    prop: InputProps
    // ...
  ): ReturnProps;
}

// inside src/index.js
const useDarkMode = (
  initialValue = false, // -> input props / config props to be exported
  {
    // -> input props / config props to be exported
    element,
    classNameDark,
    classNameLight,
    onChange,
    storageKey = "darkMode",
    storageProvider,
    global,
  } = {}
) => {
  // ...
  return {
    // -> return props to be exported
    value: state,
    enable: useCallback(() => setState(true), [setState]),
    disable: useCallback(() => setState(false), [setState]),
    toggle: useCallback(() => setState((current) => !current), [setState]),
  };
};
export default useDarkMode;

declare module "use-dark-mode" {
  /**
   * A config object allowing you to specify certain aspects of `useDarkMode`
   */
  export interface DarkModeConfig {
    classNameDark?: string; // A className to set "dark mode". Default = "dark-mode".
    classNameLight?: string; // A className to set "light mode". Default = "light-mode".
    element?: HTMLElement; // The element to apply the className. Default = `document.body`
    onChange?: (val?: boolean) => void; // Overide the default className handler with a custom callback.
    storageKey?: string; // Specify the `localStorage` key. Default = "darkMode". Set to `null` to disable persistent storage.
    storageProvider?: WindowLocalStorage; // A storage provider. Default = `localStorage`.
    global?: Window; // The global object. Default = `window`.
  }
  /**
   * An object returned from a call to `useDarkMode`.
   */
  export interface DarkMode {
    readonly value: boolean;
    enable: () => void;
    disable: () => void;
    toggle: () => void;
  }
  /**
   * A custom React Hook to help you implement a "dark mode" component for your application.
   */
  export default function useDarkMode(
    initialState?: boolean,
    config?: DarkModeConfig
  ): DarkMode;
}

Typing Exported Components #

In case of typing untyped class components, there's almost no difference in approach except for the fact that after declaring the types, you export the extend the type using class UntypedClassComponent extends React.Component<UntypedClassComponentProps, any> {} where UntypedClassComponentProps holds the type declaration.

For instance, sw-yx's Gist on React Router 6 types implemented a similar method for typing the then untyped RR6.

declare module "react-router-dom" {
  import * as React from 'react';
  // ...
  type NavigateProps<T> = {
    to: string | number,
    replace?: boolean,
    state?: T
  }
  //...
  export class Navigate<T = any> extends React.Component<NavigateProps<T>>{}
  // ...

For more information on creating type definitions for class components, you can refer to this post for reference.

Troubleshooting Handbook: Operators #

• typeof and instanceof: type query used for refinement
• keyof: get keys of an object
• O[K]: property lookup
• [K in O]: mapped types
• + or - or readonly or ?: addition and subtraction and readonly and optional modifiers
• x ? Y : Z: Conditional types for generic types, type aliases, function parameter types
• !: Nonnull assertion for nullable types
• =: Generic type parameter default for generic types
• as: type assertion
• is: type guard for function return types

Conditional Types are a difficult topic to get around so here are some extra resources:

• fully walked through explanation https://artsy.github.io/blog/2018/11/21/conditional-types-in-typescript/
• Bailing out and other advanced topics https://github.com/sw-yx/ts-spec/blob/master/conditional-types.md
• Basarat's video https://www.youtube.com/watch?v=SbVgPQDealg&list=PLYvdvJlnTOjF6aJsWWAt7kZRJvzw-en8B&index=2&t=0s
• Generics, Conditional types and Mapped types

Troubleshooting Handbook: Utilities #

These are all built in, see source in es5.d.ts:

• ConstructorParameters: a tuple of class constructor's parameter types
• Exclude: exclude a type from another type
• Extract: select a subtype that is assignable to another type
• InstanceType: the instance type you get from a newing a class constructor
• NonNullable: exclude null and undefined from a type
• Parameters: a tuple of a function's parameter types
• Partial: Make all properties in an object optional
• Readonly: Make all properties in an object readonly
• ReadonlyArray: Make an immutable array of the given type
• Pick: A subtype of an object type with a subset of its keys
• Record: A map from a key type to a value type
• Required: Make all properties in an object required
• ReturnType: A function's return type

Troubleshooting Handbook: tsconfig.json #

You can find all the Compiler options in the TypeScript docs. The new TS docs also has per-flag annotations of what each does. This is the setup I roll with for APPS (not libraries - for libraries you may wish to see the settings we use in tsdx):

{
  "compilerOptions": {
    "incremental": true,
    "outDir": "build/lib",
    "target": "es5",
    "module": "esnext",
    "lib": ["dom", "esnext"],
    "sourceMap": true,
    "importHelpers": true,
    "declaration": true,
    "rootDir": "src",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "allowJs": false,
    "jsx": "react",
    "moduleResolution": "node",
    "baseUrl": "src",
    "forceConsistentCasingInFileNames": true,
    "esModuleInterop": true,
    "suppressImplicitAnyIndexErrors": true,
    "allowSyntheticDefaultImports": true,
    "experimentalDecorators": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "build", "scripts"]
}

You can find more recommended TS config here.

Please open an issue and discuss if there are better recommended choices for React.

Selected flags and why we like them:

• esModuleInterop: disables namespace imports (import * as foo from "foo") and enables CJS/AMD/UMD style imports (import fs from "fs")
• strict: strictPropertyInitialization forces you to initialize class properties or explicitly declare that they can be undefined. You can opt out of this with a definite assignment assertion.
• "typeRoots": ["./typings", "./node_modules/@types"]: By default, TypeScript looks in node_modules/@types and parent folders for third party type declarations. You may wish to override this default resolution so you can put all your global type declarations in a special typings folder.

Compilation speed grows linearly with size of codebase. For large projects, you will want to use Project References. See our ADVANCED cheatsheet for commentary.

Troubleshooting Handbook: Fixing bugs in official typings #

If you run into bugs with your library's official typings, you can copy them locally and tell TypeScript to use your local version using the "paths" field. In your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "mobx-react": ["../typings/modules/mobx-react"]
    }
  }
}

Thanks to @adamrackis for the tip.

If you just need to add an interface, or add missing members to an existing interface, you don't need to copy the whole typing package. Instead, you can use declaration merging:

// my-typings.ts
declare module "plotly.js" {
  interface PlotlyHTMLElement {
    removeAllListeners(): void;
  }
}

// MyComponent.tsx
import { PlotlyHTMLElement } from "plotly.js";

const f = (e: PlotlyHTMLElement) => {
  e.removeAllListeners();
};

You dont always have to implement the module, you can simply import the module as any for a quick start:

// my-typings.ts
declare module "plotly.js"; // each of its imports are `any`

Because you don't have to explicitly import this, this is known as an ambient module declaration. You can do AMD's in a script-mode .ts file (no imports or exports), or a .d.ts file anywhere in your project.

You can also do ambient variable and ambient type declarations:

// ambient utiltity type
type ToArray<T> = T extends unknown[] ? T : T[];
// ambient variable
declare let process: {
  env: {
    NODE_ENV: "development" | "production";
  };
};
process = {
  env: {
    NODE_ENV: "production",
  },
};

You can see examples of these included in the built in type declarations in the lib field of tsconfig.json

Time to Really Learn TypeScript #

Believe it or not, we have only barely introduced TypeScript here in this cheatsheet. If you are still facing TypeScript troubleshooting issues, it is likely that your understanding of TS is still too superficial.

There is a whole world of generic type logic that you will eventually get into, however it becomes far less dealing with React than just getting good at TypeScript so it is out of scope here. But at least you can get productive in React now :)

It is worth mentioning some resources to help you get started:

• Step through the 40+ examples under the playground's Examples section, written by @Orta
• Anders Hejlsberg's overview of TS: https://www.youtube.com/watch?v=ET4kT88JRXs
• Marius Schultz: https://blog.mariusschulz.com/series/typescript-evolution with an Egghead.io course
• Basarat's Deep Dive: https://basarat.gitbook.io/typescript/
• Axel Rauschmeyer's Tackling TypeScript
• Rares Matei: Egghead.io course's advanced TypeScript course on Egghead.io is great for newer typescript features and practical type logic applications (e.g. recursively making all properties of a type readonly)
• Learn about Generics, Conditional types and Mapped types
• Shu Uesugi: TypeScript for Beginner Programmers
• Here is another TypeScript Error Guide that you can check for your errors.

Other React + TypeScript resources #

• me! https://twitter.com/swyx
• https://www.freecodecamp.org/news/how-to-build-a-todo-app-with-react-typescript-nodejs-and-mongodb/
• https://github.com/piotrwitek/react-redux-typescript-guide - HIGHLY HIGHLY RECOMMENDED, i wrote this repo before knowing about this one, this has a lot of stuff I don't cover, including REDUX and JEST.
• 10 Bad TypeScript Habits:
  1. not using "strict": true
  2. using || for default values when we have ??
  3. Using any instead of unknown for API responses
  4. using as assertion instead of Type Guards (function isFoo(obj: unknown): obj is Foo {})
  5. as any in tests
  6. Marking optional properties instead of modeling which combinations exist by extending interfaces
  7. One letter generics
  8. Non-boolean if (nonboolean) checks
  9. bangbang checks if (!!nonboolean)
  10. != null to check for null and undefined
• Ultimate React Component Patterns with TypeScript 2.8
• Basarat's TypeScript gitbook has a React section with an Egghead.io course as well.
• Palmer Group's TypeScript + React Guidelines as well as Jared's other work like disco.chat
• Sindre Sorhus' TypeScript Style Guide
• TypeScript React Starter Template by Microsoft A starter template for TypeScript and React with a detailed README describing how to use the two together. Note: this doesnt seem to be frequently updated anymore.
• Brian Holt's Intermediate React course on Frontend Masters (paid) - Converting App To TypeScript Section
• Mike North's Production TypeScript course on Frontend Masters (paid)
• TSX Guide by gojutin
• TypeScript conversion:
  • Lyft's React-To-TypeScript conversion CLI
  • Gustav Wengel's blogpost - converting a React codebase to TypeScript
  • Microsoft React TypeScript conversion guide
• You?.

Editor Tooling and Integration #

• VSCode
  • swyx's VSCode Extension: https://github.com/sw-yx/swyx-react-typescript-snippets
  • amVim: https://marketplace.visualstudio.com/items?itemName=auiworks.amvim
• VIM
  • https://github.com/Quramy/tsuquyomi
  • nvim-typescript?
  • https://github.com/leafgarland/typescript-vim
  • peitalin/vim-jsx-typescript
  • NeoVim: https://github.com/neoclide/coc.nvim
  • other discussion: https://mobile.twitter.com/ryanflorence/status/1085715595994095620

You are free to use this repo's TSX logo if you wish:

You may also wish to use alternative logos - jsx-tsx-logos

Linting #

⚠️Note that TSLint is now in maintenance and you should try to use ESLint instead. If you are interested in TSLint tips, please check this PR from @azdanov. The rest of this section just focuses on ESLint. You can convert TSlint to ESlint with this tool.

⚠️This is an evolving topic. typescript-eslint-parser is no longer maintained and work has recently begun on typescript-eslint in the ESLint community to bring ESLint up to full parity and interop with TSLint.

Follow the TypeScript + ESLint docs at https://github.com/typescript-eslint/typescript-eslint:

yarn add -D @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint

add a lint script to your package.json:

  "scripts": {
    "lint": "eslint 'src/**/*.ts'"
  },

and a suitable .eslintrc.js (using .js over .json here so we can add comments):

module.exports = {
  env: {
    es6: true,
    node: true,
    jest: true,
  },
  extends: "eslint:recommended",
  parser: "@typescript-eslint/parser",
  plugins: ["@typescript-eslint"],
  parserOptions: {
    ecmaVersion: 2017,
    sourceType: "module",
  },
  rules: {
    indent: ["error", 2],
    "linebreak-style": ["error", "unix"],
    quotes: ["error", "single"],
    "no-console": "warn",
    "no-unused-vars": "off",
    "@typescript-eslint/no-unused-vars": [
      "error",
      { vars: "all", args: "after-used", ignoreRestSiblings: false },
    ],
    "@typescript-eslint/explicit-function-return-type": "warn", // Consider using explicit annotations for object literals and function return types even when they can be inferred.
    "no-empty": "warn",
  },
};

Most of this is taken from the tsdx PR which is for libraries.

More .eslintrc.json options to consider with more options you may want for apps:

{
  "extends": [
    "airbnb",
    "prettier",
    "prettier/react",
    "plugin:prettier/recommended",
    "plugin:jest/recommended",
    "plugin:unicorn/recommended"
  ],
  "plugins": ["prettier", "jest", "unicorn"],
  "parserOptions": {
    "sourceType": "module",
    "ecmaFeatures": {
      "jsx": true
    }
  },
  "env": {
    "es6": true,
    "browser": true,
    "jest": true
  },
  "settings": {
    "import/resolver": {
      "node": {
        "extensions": [".js", ".jsx", ".ts", ".tsx"]
      }
    }
  },
  "overrides": [
    {
      "files": ["**/*.ts", "**/*.tsx"],
      "parser": "typescript-eslint-parser",
      "rules": {
        "no-undef": "off"
      }
    }
  ]
}

You can read a fuller TypeScript + ESLint setup guide here from Matterhorn, in particular check https://github.com/MatterhornDev/learn-typescript-linting.

Another great resource is "Using ESLint and Prettier in a TypeScript Project" by @robertcoopercode.

Wes Bos is also working on TypeScript support for his eslint+prettier config.

If you're looking for information on Prettier, check out the Prettier guide.

Other React + TypeScript resources #

• me! https://twitter.com/swyx
• https://github.com/piotrwitek/react-redux-typescript-guide - HIGHLY HIGHLY RECOMMENDED, i wrote this repo before knowing about this one, this has a lot of stuff I don't cover, including REDUX and JEST.
• Ultimate React Component Patterns with TypeScript 2.8
• Basarat's TypeScript gitbook has a React section with an Egghead.io course as well.
• Palmer Group's TypeScript + React Guidelines as well as Jared's other work like disco.chat
• Stefan Baumgartner's TypeScript + React Guide, which serves as a side-by-side guide to the official docs with extra articles on styling, custom hooks and patterns
• Sindre Sorhus' TypeScript Style Guide
• TypeScript React Starter Template by Microsoft A starter template for TypeScript and React with a detailed README describing how to use the two together. Note: this doesnt seem to be frequently updated anymore.
• Brian Holt's Intermediate React course on Frontend Masters (paid) - Converting App To TypeScript Section
• TypeScript conversion:
  • Lyft's React-To-TypeScript conversion CLI
  • Gustav Wengel's blogpost - converting a React codebase to TypeScript
  • Microsoft React TypeScript conversion guide
• DefinitelyTyped React source code
• You?.