overloads Function Overloads
Last updated: 2026-10-22
overloads Function Overloads
Overload declarations give one function several signature sheets: callers get a precise return type per argument shape while the implementation is written once. TS matches top to bottom and errors only if none fits.
| Group | Functions & Classes |
|---|---|
| Kind | Syntax |
| Strict mode | Not required |
ℹ️ Info The editor transpiles TypeScript to JavaScript and runs it (no type checking); see each example's Output for type-check results.
📝 Syntax
function format(value: number): string; // number → amount
function format(value: Date): string; // Date → date string
function format(value: number | Date): string { // impl signature is invisible to callers
return value instanceof Date
? value.toISOString().slice(0, 10)
: `$${value.toFixed(2)}`;
}⚙️ Parameters
| f(...): T; | Declarations without bodies, written consecutively; matched in order |
|---|---|
| f(...) { } | The single signature with a body; its parameters must be compatible with every overload, yet it is invisible to callers |
Returns：Determined by the matched overload — each overload may declare its own return type, so callers get the precise type for their argument shape.
▶ Example
Edit the code below and click Try it to see the transpiled result:
Output：
$42.00
2026-01-15
(Runtime output after transpilation; overload signatures vanish — only the implementation runs, zero branch overhead)💡 Notes
ℹ️ Info Only the implementation survives compilation — overload signatures are compile-time syntax with zero runtime footprint.
⚠️ Note The implementation signature is invisible to callers: its parameters must cover every overload, otherwise valid calls error against it.
💡 Tip Overloads match top-down: put specific signatures first and loose ones last, or a loose signature steals calls meant for a specific one.
🏷️ Related Functions & Classes
💡 Related cases
More cases coming soon.
📚 Related tutorials
❓ FAQ
Q Overloads or a union parameter?
A Overloads when the argument type changes the return type (a precise sheet each); a union parameter plus narrowing when it only affects internal logic and the return is the same.
Q Why do I get "no overload matches this call"?
A Check two things: whether the arguments truly fit some overload, and whether the order makes sense (a loose signature early blocks specific ones later).
Q Can arrow functions have overloads?
A No. Overloads require function declarations; for variables, use the object-type form type Overloaded = { (x: string): A; (x: number): B }.
