← Back to glossary

TypeScript Function Overloads

typescript Intermediate

Also Known As

function overloads TypeScript overloads overload signatures

TL;DR

TypeScript function overloads allow a single function to accept different argument shapes and return different types based on which overload signature matches — providing precise type checking that union types alone cannot express.

Explanation

A function overload consists of two or more overload signatures (no body) followed by one implementation signature (with body). TypeScript uses the overload signatures for type checking and IDE autocomplete — the implementation signature is hidden from callers. Overloads are useful when the return type depends on the input type (e.g. createElement('div') returns HTMLDivElement, createElement('canvas') returns HTMLCanvasElement), or when a function accepts fundamentally different argument shapes. The implementation must be compatible with all overload signatures. Method overloads work the same way in classes.

Common Misconception

✗ The implementation signature is visible to callers. It is not — callers only see the overload signatures. The implementation signature is often broader (using union types) and would be confusing or permissive if exposed.

Why It Matters

Without overloads, functions that return different types based on input force callers to narrow the type themselves or use unsafe casts. Overloads encode the relationship between input and output types precisely — 'when you pass a string you get a string back, when you pass a number you get a number back' — making the API self-documenting and type-safe.

Common Mistakes

Putting the implementation signature before the overload signatures — TypeScript requires all overload signatures first, then the implementation.
Making the implementation signature narrower than the overloads — the implementation must accept the union of all overload parameters.
Using overloads when conditional types or generics would be cleaner — overloads are best for a small number of distinct cases; for many cases use generics with conditional return types.
Exposing too many overloads — each overload adds cognitive load; prefer 2–4 well-chosen overloads over exhaustive enumeration.

Code Examples

✗ Vulnerable

// ❌ Union return type — caller must narrow every time
function parseInput(input: string | number): string | number {
    if (typeof input === 'string') return input.toUpperCase();
    return input * 2;
}

const result = parseInput('hello');
// result: string | number — TypeScript doesn't know it's string
result.toUpperCase(); // Error: Property 'toUpperCase' does not exist on type 'string | number'

✓ Fixed

// ✅ Overloads — return type matches input type
function parseInput(input: string): string;
function parseInput(input: number): number;
function parseInput(input: string | number): string | number {
    if (typeof input === 'string') return input.toUpperCase();
    return input * 2;
}

const s = parseInput('hello'); // TypeScript knows: string
s.toUpperCase();                // ✓ No error

const n = parseInput(42);       // TypeScript knows: number
n.toFixed(2);                   // ✓ No error

// Class method overload
class EventEmitter {
    on(event: 'data',  listener: (data: Buffer) => void): this;
    on(event: 'error', listener: (err: Error)  => void): this;
    on(event: string,  listener: Function):                this {
        // implementation
        return this;
    }
}

References

↗ https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads