React TypeScript Cheatsheet

If you prefer not to use custom hooks with runtime checks, you can use TypeScript assertions to bypass null checks. Note that these are less safe than runtime checks because they hide errors that would otherwise be caught during execution.

Common patterns include:

• Non-null assertion operator (!): Use contextValue!.property when consuming.
• Casting an empty object: createContext<T>({} as T).
• Casting null: createContext<T>(null!).

Recommendation: Prefer runtime checking and throwing errors over type assertion to ensure better debugging visibility.

// Option 1: Non-null assertion during consumption
const currentUser = use(CurrentUserContext);
const name = currentUser!.username;

// Option 2: Casting empty object as default
const CurrentUserContext = createContext<CurrentUserContextType>(
  {} as CurrentUserContextType,
);

// Option 3: Casting null as non-null default
const CurrentUserContext = createContext<CurrentUserContextType>(null!);

When you want a component to accept either a complete set of props or no props at all, you have two main approaches:

1. Grouping props in an optional object: Wrap the required props in a single optional property. This ensures that if the property is provided, all its internal fields must be present.
2. Using Record<string, never>: This represents an empty object, but it is not officially recommended by the TypeScript team.

Grouping in an optional object is the cleaner, more idi-omatic approach.

// Recommended: Grouping required props in an optional object
interface Props {
  obj?: {
    a: string;
    b: string;
  };
}

const AllOrNothing = (props: Props) => {
  if (props.obj) {
    return <>{props.obj.a}</>;
  }
  return <>Nothing</>;
};

const Component = () => (
  <>
    <AllOrNothing /> {/* ok */}
    <AllOrNothing obj={{ a: "", b: "" }} /> {/* ok */}
    <AllOrNothing obj={{ a: "" }} /> {/* error */}
  </>
);

Concurrent React APIs allow you to keep the UI responsive during heavy rendering or data fetching.

Suspense

Declaratively show a fallback UI while children are loading (e.g., waiting for a promise via use or a lazy component).

use

Reads the value of a context or a promise. Unlike useContext, use can be called inside conditions and loops and integrates with Suspense for promises.

useTransition

Marks a state update as non-urgent. This prevents heavy renders from blocking urgent interactions like typing or scrolling.

• Async Transitions (React 19): The function passed to startTransition can be async. isPending will remain true until the entire async operation completes.

useDeferredValue

Defers re-rendering a part of the UI that is expensive to compute. The deferred value lags behind the actual value, allowing urgent updates to flush first.

• initialValue (React 19): Accepts a second argument to provide a value to use during the initial render before the deferred value catches up.

// Suspense + use
const UserProfile = ({ userPromise }: { userPromise: Promise<User> }) => {
  const user = use(userPromise);
  return <p>{user.name}</p>;
};

// useTransition
const [isPending, startTransition] = useTransition();
const selectTab = (next: string) => {
  startTransition(() => {
    setTab(next);
  });
};

// useDeferredValue
const deferredQuery = useDeferredValue(query, "");

Discriminated Unions allow you to create component props where the availability of certain properties depends on a specific 'discriminant' key. This is highly effective for complex state or event handling.

Warning: TypeScript does not narrow Discriminated Unions based on typeof checks of the values. You must check the value of the discriminant key itself (e.g., if (event.type === 'TextEvent')) rather than checking the type of a property (e.g., if (typeof event.value === 'string')).

type UserTextEvent = { type: "TextEvent"; value: string; target: HTMLInputElement };
type UserMouseEvent = { type: "MouseEvent"; value: [number, number]; target: HTMLElement };
type UserEvent = UserTextEvent | UserMouseEvent;

function handle(event: UserEvent) {
  if (event.type === "TextEvent") {
    event.value; // string
    event.target; // HTMLInputElement
    return;
  }
  event.value; // [number, number]
  event.target; // HTMLElement
}

To enforce that a component accepts either propA or propB, but never both simultaneously, you can use a union of types where the unwanted prop is explicitly typed as never.

Alternatively, a more robust pattern is using a discriminated union with a type prop. This is often preferred as it provides clearer error messages and easier type narrowing within the component logic.

// Pattern 1: Using `never` to disallow both
type Props1 = { foo: string; bar?: never };
type Props2 = { bar: string; foo?: never };
const OneOrTheOther = (props: Props1 | Props2) => {
  if ("foo" in props && typeof props.foo === "string") {
    return <>{props.foo}</>;
  }
  return <>{props.bar}</>;
};

// Pattern 2: Using a discriminant prop (Recommended)
type Props1 = { type: "foo"; foo: string };
type Props2 = { type: "bar"; bar: string };

const OneOrTheOther = (props: Props1 | Props2) => {
  if (props.type === "foo") {
    return <>{props.foo}</>;
  }
  return <>{props.bar}</>;
};

Instead of traditional error handling, you can use functional patterns like Option (also known as Maybe) to represent values that might be absent. This involves using an interface with methods like flatMap and getOrElse to chain operations safely without explicit null or error checks at every step.

interface Option<T> {
  flatMap<U>(f: (value: T) => None): None;
  flatMap<U>(f: (value: T) => Option<U>): Option<U>; // Note: simplified for example
  getOrElse(value: T): T;
}

class Some<T> implements Option<T> {
  constructor(private value: T) {}
  flatMap<U>(f: (value: T) => Option<U>): Option<U> {
    return f(this.value);
  }
  getOrElse(): T {
    return this.value;
  }
}

class None implements Option<never> {
  flatMap<U>(): None {
    return this;
  }
  getOrElse<U>(value: U): U {
    return value;
  }
}

// Usage:
let result = Option(6)
  .flatMap((n) => Option(n * 3))
  .getOrElse(7);