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.
function pad(value: string): string; function pad(value: number): number; function pad(value: string | number): string | number { return value; }
Try it
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.
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
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.