Lesson 20 of 80

Function Overloads

Q: When would you reach for function overloads instead of a single function with a union-typed parameter?

A strong answer covers: When the return type's shape genuinely depends on which branch of a union parameter was passed, not just the parameter type itself; Overload declarations are what callers see/get checked against; a separate, wider implementation signature provides the actual body and is invisible to callers; Overloads are checked top-to-bottom, first match wins, and this is purely compile-time — it compiles to one plain JS function.

One function, several distinct call signatures — for the specific case where a single union-typed parameter can't express how the return type actually depends on which shape of argument was passed.

11 min read

Check your understanding

Every option explains itself — why the right one is right, and why each wrong one is wrong. Miss one and it comes back later on a spaced-repetition schedule.

Question 1 of 2

Is the implementation signature (the third, most general one) itself an overload that a caller could match against?

No — it's invisible to callers; only the declared overloads above it are checked against callsYes — it's simply the most general overload and callers can match it directlyYes, but only when none of the other overloads match

Stuck? Ask the AI tutor

Hints without spoilers, and a plain explanation of why a wrong answer was wrong — answered only from this lesson. Free account, no card.

Interview questions on Function Overloads

What interviewers actually ask about this, and what a strong answer has to cover.

When would you reach for function overloads instead of a single function with a union-typed parameter?

A strong answer covers

When the return type's shape genuinely depends on which branch of a union parameter was passed, not just the parameter type itself
Overload declarations are what callers see/get checked against; a separate, wider implementation signature provides the actual body and is invisible to callers
Overloads are checked top-to-bottom, first match wins, and this is purely compile-time — it compiles to one plain JS function

Likely follow-ups

What happens if you order two overloads so a more general one comes before a more specific one that could also match?
Is the implementation signature one of the overloads callers can match against?
Can you think of a real standard-library function that likely uses overloads internally?

Practice these with the AI interviewer →

The plain-language idea

function getElement(id: string): HTMLElement | null;
function getElement(index: number): HTMLElement | undefined;
function getElement(idOrIndex: string | number): HTMLElement | null | undefined {
  // one real implementation, handling both cases
  return typeof idOrIndex === "string"
    ? document.getElementById(idOrIndex)
    : document.querySelectorAll("*")[idOrIndex];
}

The first two signatures are overload declarations — they're what callers actually see and get checked against. The third, wider one is the implementation signature — it must be compatible with every overload above it, but callers never call it directly and it never shows up in autocomplete.

Calling getElement("app") resolves to the first overload's return type (HTMLElement | null); calling getElement(3) resolves to the second's (HTMLElement | undefined) — a single union-typed parameter/return ((idOrIndex: string | number): HTMLElement | null | undefined) couldn't express that the return type's nullability depends on which argument type was actually passed.

Function overloads: many declared shapes, one real bodyStep 1 of 3

function makeDate(ts: number): Date; function makeDate(y: number, m: number, d: number): Date; — multiple call signatures declared.

What people usually miss

Watch out

The implementation signature is not one of the overloads — it's deliberately more permissive (often using unions or any) and is invisible to callers; only the overload declarations above it are checked against call sites.
Overloads are checked top to bottom, first match wins. A more specific overload should come before a more general one that could also match the same argument, or the general one will shadow it.
This is a JavaScript-flavored form of what other languages call "overloading" at the function-signature level only — TypeScript still compiles to one plain JS function; there's no runtime dispatch based on argument types the way true overloading works in some other languages.

Why this matters in interviews

Overloads come up less often than generics or unions, but recognizing when a union parameter genuinely isn't enough — because the return type's shape depends on which union branch was passed — is a precise, senior-level signal when it comes up.