Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Literal and Object Types

TypeScript function overloads

Reference for TypeScript function overloads: overload and implementation signatures, resolution order, compatibility rules, method overloads and generic alternatives.

Overloads let one function have several call signatures. You list the overload signatures (declarations with no body), then write one implementation signature with a body that handles every case. Callers see only the overloads; the implementation signature is not callable from outside.

Use overloads when the return type depends on which argument shape was passed, which a single union-typed signature cannot express.

TypeScript
function pad(value: string): string;
function pad(value: number): number;
function pad(value: string | number): string | number {
  return value;
}

Try it

TypeScript Return type depends on arguments

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Order matters, and method overloads

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
function name(a: A): R1;            // overload signature 1
function name(a: A, b: B): R2;      // overload signature 2
function name(a: A, b?: B): R1 | R2 { /* implementation */ }

interface I { m(x: string): string; m(x: number): number; }
type T = { (x: string): string; (x: number): number };
Rule Description
Adjacent Overload signatures and the implementation must be consecutive declarations.
Compatible Each overload must be assignable to the implementation signature (parameters and return type loosely related).
Resolution The compiler tries overloads top to bottom and uses the first one whose parameters accept the arguments.
Visibility Only overload signatures are part of the public type; the implementation signature is hidden.

Edge cases: all overloads must agree on being exported or not. In ambient contexts (declare function, .d.ts files) you write only signatures. Arrow functions cannot be overloaded directly; use a function declaration or a type with call signatures.

Usage notes

  • Specific first: put narrow signatures before general ones, or the general one will always win.
  • No union arguments: a call with a union-typed argument does not match separate overloads for each member. Add an overload for the union if needed.
  • Prefer optional parameters when overloads differ only in trailing arguments, and prefer a union parameter when the return type is the same.
  • Generics with conditional types can replace overloads, but they usually need an internal cast, as in the second example.
  • Number of overloads: keep it small; error messages for failed calls list only the last overload tried, which can confuse readers.
  • Runtime: overloads erase completely; the implementation must test its arguments itself.