DEV Community

Cover image for Discriminated Unions in TypeScript: How They Differ from Plain Type Unions
Arka Chakraborty
Arka Chakraborty

Posted on

Discriminated Unions in TypeScript: How They Differ from Plain Type Unions

#react #webdev #javascript #typescript

Type Union vs Discriminated Unions

All unions are not equal, some are smart enough to know what fields exist in each branch.

🧠Context

React components often handle multiple states: forms (loading, success, error), modals (open, closed), or API responses (data vs error).
A common confusion is the difference between plain type unions and discriminated unions. Understanding this distinction helps you write safer, more maintainable React components.

📌Plain Type Unions

A plain union is a type that can hold multiple literal values or types, but TypeScript does not associate additional fields with each value.

type Status = "loading" | "success" | "error";

function render(status: Status) {
  if (status === "success") {
    // ❌ Can't attach extra info like "data"
    return "Form submitted!";
  }
  return "Not submitted";
}
Enter fullscreen mode Exit fullscreen mode

⚠️Limitations of plain unions:

  • No structured data per state
  • No automatic type narrowing for properties
  • Good only for simple flags

📌Discriminated Unions

  • A discriminated union is a union of objects where each object has:
  • A discriminant property (usually a literal string like "status" or "type")
  • Optional additional fields unique to that branch

📝How TypeScript narrows types

type FormState =
  | { status: "loading" }
  | { status: "success"; data: string }
  | { status: "error"; message: string };

function renderForm(state: FormState) {
  if (state.status === "loading") return <p>Loading...</p>;
  if (state.status === "success") return <p>Submitted: {state.data}</p>;
  if (state.status === "error") return <p>Error: {state.message}</p>;
}
Enter fullscreen mode Exit fullscreen mode
  • TS automatically narrows the type of state based on the discriminant (status)
  • Each branch has access only to its relevant fields (data, message)

📌With vs Without Discriminated Unions

//Without discriminated unions

type FormState = "loading" | "success" | "error";

function renderForm(state: FormState) {
  if (state === "success") {
    // ❌ Can't attach extra info like data
    return "Form submitted!";
  }
}
Enter fullscreen mode Exit fullscreen mode 
//With discriminated unions

type FormState =
  | { status: "loading" }
  | { status: "success"; data: string }
  | { status: "error"; message: string };

function renderForm(state: FormState) {
  if (state.status === "success") {
    // ✅ TS knows 'data' exists
    return `Form submitted with: ${state.data}`;
  }
}
Enter fullscreen mode Exit fullscreen mode

💡Real-Life React Use Cases

Form State Example

type FormState =
  | { status: "idle" }
  | { status: "submitting" }
  | { status: "success"; result: string }
  | { status: "error"; message: string };

function Form({ state }: { state: FormState }) {
  switch (state.status) {
    case "idle": return <button>Submit</button>;
    case "submitting": return <p>Submitting...</p>;
    case "success": return <p>{state.result}</p>;
    case "error": return <p>{state.message}</p>;
  }
}
Enter fullscreen mode Exit fullscreen mode

Modal Example

type ModalState =
  | { open: true; content: string }
  | { open: false };

function Modal({ state }: { state: ModalState }) {
  if (!state.open) return null;
  return <div>{state.content}</div>;
}
Enter fullscreen mode Exit fullscreen mode

📌Key Takeaways

  • Plain unions are fine for flags, but they cannot carry per-case data.
  • Discriminated unions let TypeScript know exactly which fields exist per case, making components safer.
  • For React apps, always prefer discriminated unions for component states, API responses, and mutually exclusive props.

Top comments (0)