TypeScript Optional Parameters, Default Values and Rest

Add ? after a parameter name to make it optional. Callers may leave it out, and inside the function its type includes undefined.

function greet(name: string, title?: string): string {
  // title is string | undefined here
  return title ? `Hello, ${title} ${name}` : `Hello, ${name}`;
}

console.log(greet("Lovelace"));          // Hello, Lovelace
console.log(greet("Lovelace", "Lady"));  // Hello, Lady Lovelace

TypeScript checks the argument count, so without the ? the first call would be a compile error: Expected 2 arguments, but got 1. (TS2554).

Optional Parameters Are Possibly undefined

Because a caller can omit it, an optional parameter's type inside the function is T | undefined. Under strictNullChecks you must handle the undefined case before using it as a T.

function formatPrice(amount: number, currency?: string): string {
  // currency.toUpperCase() here would fail: 'currency' is possibly 'undefined'. (TS18048)
  const code = currency?.toUpperCase() ?? "USD";
  return `${amount.toFixed(2)} ${code}`;
}

console.log(formatPrice(9.5));        // 9.50 USD
console.log(formatPrice(12, "eur"));  // 12.00 EUR

Optional chaining (?.) and nullish coalescing (??) are the usual tools here. When the fallback is a fixed value, a default parameter is shorter.

Default Parameter Values

A default value makes the parameter optional for callers and gives it a type without undefined inside the function. The type is inferred from the default, so the annotation is often unnecessary.

function repeat(text: string, times = 2, separator: string = " "): string {
  // times: number, separator: string (never undefined here)
  return Array.from({ length: times }, () => text).join(separator);
}

console.log(repeat("ha"));              // ha ha
console.log(repeat("ha", 3, "-"));      // ha-ha-ha
console.log(repeat("ha", undefined, "")); // haha

The caller sees the signature repeat(text: string, times?: number, separator?: string). Defaults follow JavaScript's rule: they apply when the argument is undefined, whether omitted or passed explicitly, and not when it is null. A default expression can use earlier parameters: function range(start: number, end = start + 10).

Parameter Order Rules

A defaulted parameter before a required one is legal but awkward. Its type for callers becomes number | undefined, and nobody enjoys writing undefined as a placeholder. If you need a flexible leading parameter, use an options object or function overloading instead.

Omitted vs undefined

x?: number and x: number | undefined look alike and have the same type inside the function. They differ for the caller: the first may be omitted, the second must be passed.

function a(x?: number) { return x; }
function b(x: number | undefined) { return x; }

console.log(a());          // undefined
console.log(b(undefined)); // undefined
// @ts-expect-error: Expected 1 arguments, but got 0.
b();

Use | undefined for a required argument that is allowed to have no value, so every caller has to think about it. Use ? when leaving it out is a normal call. (The message really says "1 arguments": that is TypeScript's wording.)

Rest Parameters

A rest parameter, ...name: T[], collects any number of arguments into an array. It must be the last parameter.

function sum(...values: number[]): number {
  return values.reduce((total, v) => total + v, 0);
}

function tag(name: string, ...classes: string[]): string {
  return `<${name} class="${classes.join(" ")}">`;
}

console.log(sum());             // 0
console.log(sum(1, 2, 3));      // 6
const scores = [4, 8, 15];
console.log(sum(...scores));    // 27
console.log(tag("div", "card", "wide")); // <div class="card wide">

Spreading an array into fixed parameters is stricter. A rest parameter accepts a spread of any number[], but a function declared (a: number, b: number) only accepts a spread of a tuple, because TypeScript must know the length:

function point(x: number, y: number) { return { x, y }; }

const list = [3, 4];            // number[]
point(...list);
// error TS2556: A spread argument must either have a tuple type or be passed to a rest parameter.

const pair = [3, 4] as const;   // readonly [3, 4]
point(...pair);                 // fine

A rest parameter can also have a tuple type, which types each position: ...args: [name: string, age?: number].

Options Objects

Once a function has more than two or three optional parameters, callers lose track of positions. An options object with defaults gives named, order-free arguments.

interface FetchOptions {
  retries?: number;
  timeoutMs?: number;
  verbose?: boolean;
}

function fetchData(url: string, { retries = 3, timeoutMs = 5000, verbose = false }: FetchOptions = {}): string {
  return `${url} retries=${retries} timeout=${timeoutMs} verbose=${verbose}`;
}

console.log(fetchData("/a"));
// /a retries=3 timeout=5000 verbose=false
console.log(fetchData("/b", { verbose: true }));
// /b retries=3 timeout=5000 verbose=true

The = {} at the end makes the whole object optional. Without it, fetchData("/a") is a compile error (Expected 2 arguments, but got 1., TS2554), and in plain JavaScript the same call would throw a TypeError at run time, because destructuring needs an object to read from.

Optional Parameters in Callback Types

In a function type, ? means "the caller of this callback may not pass it". It does not mean "the callback may skip it": a callback can always ignore trailing parameters. So do not mark callback parameters optional just to let handlers take fewer arguments.

// Too loose: every handler must now cope with index being undefined
type Visit = (item: string, index?: number) => void;

// Right: the caller always passes both; handlers may use only item
type VisitStrict = (item: string, index: number) => void;
const log: VisitStrict = (item) => console.log(item);