Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

TypeScript Generic Parameter Defaults: Syntax, Precedence, and Inference

When a default applies and when inference wins, defaults that reference earlier parameters, and how a defaulted type parameter keeps a library change non-breaking.

~6 min readTypeScript
#TypeScript#Generics#Type Inference
3D illustration of generic parameter slots filling with default type blocks when no type arguments are supplied

A generic parameter default (<T = string>) supplies the type argument when the caller does not, and sometimes when inference cannot. It is the type-level equivalent of a parameter default, with one important difference: the default never overrides inference. If the compiler can infer a type argument from the arguments, the inferred type wins even when a default exists; the default is used only in the cases where nothing else filled the slot. That asymmetry decides most of the behavior, including why a defaulted parameter can still be inferred as unknown.

Quick Summary

  • Syntax is <T = Default> on functions, classes, type aliases, interfaces, and methods; defaults may reference earlier parameters (<K extends string, V = K>).
  • The default must satisfy the constraint (TS2344), and it may only reference parameters declared to its left (TS2744).
  • Inference takes priority: a parameter with an inference site is filled from the argument list, and the default applies only when inference produces nothing.
  • Without a default, a parameter that cannot be inferred becomes unknown (since TypeScript 3.5), not any and not {}.
  • Type arguments are positional and cannot be skipped: f<string, > is invalid, so a defaulted parameter must come after every required one.
  • A default makes the parameter optional at the call site, which changes a generic type from "requires N arguments" (TS2314) to "requires between N and M" (TS2707).
  • In a class, the default is fixed at the declaration: new Api() uses it, and there is no way to override only a later parameter.
  • Adding a new generic parameter with a default is a non-breaking library change; without one it breaks every existing call.

Basic syntax and type signatures

typescript
// Function with a default. function createBox<T = string>(value: T): { value: T } { return { value }; } createBox("a"); // T inferred as string createBox<number>(1); // explicit // Type alias and interface defaults. type ApiResponse<T = unknown, E = Error> = { data: T; error?: E }; type Paged<T = unknown> = { items: T[]; page: number }; interface Repository<T extends { id: string } = { id: string }> { find(id: string): T | undefined; } // Default referencing an earlier parameter. type Mapper<K extends PropertyKey, V = K> = (key: K, value: V) => void; type Keys = Mapper<"a" | "b">; // (key: "a" | "b", value: "a" | "b") => void // Class default. class Cache<T = string> { private store = new Map<string, T>(); get(key: string): T | undefined { return this.store.get(key); } set(key: string, value: T): void { this.store.set(key, value); } } const defaultCache = new Cache(); // Cache<string> const numberCache = new Cache<number>(); // Cache<number>

The rule about ordering follows from the call syntax:

typescript
function pair<A, B = A>(a: A, b: B): [A, B] { return [a, b]; } pair(1, "x"); // A = number, B = string (inference) pair<string>("a", "b"); // A given, B inferred as string function bad<A = string, B>(a: A, b: B): [A, B] { return [a, b]; } // TS2706: Required type parameters may not follow optional type parameters.

Once a parameter has a default, every parameter after it must also have one. That is why defaults live at the end of a parameter list in practice.

Comparison of inference and default behavior

SituationWithout a defaultWith a default
Argument provides an inference siteinferred typeinferred type; default ignored
No inference site, no type argumentunknownthe default
Explicit type argument givenusedused; default ignored
Partial type argument listnot possibletrailing defaults may be omitted
Constraint violated by the defaultn/aTS2344 on the declaration
Caller overrides with undefinednot applicablenot applicable: type arguments are types, not values

The third row is worth internalizing: a default is not a fallback for a failed inference in the sense of "try, and if it comes out weird use the default". It is a fallback for the absence of any inference at all. A parameter inferred as string | undefined from an argument keeps string | undefined; the default never intervenes.

Practical edge cases and deep dives

1. Defaults that only apply when the call says nothing

typescript
function useApi<T = unknown, E = Error>( fetcher: () => Promise<T>, ): { data: T | undefined; error: E | undefined } { throw new Error("unimplemented"); } const a = useApi(async () => ({ id: 1 })); // T = { id: number } const b = useApi(async () => { throw new Error("x"); }); // T = unknown (never inferred) const c = useApi<number>(async () => 1); // explicit interface Request<Body = unknown, Query = Record<string, string>> { body: Body; query: Query; } const empty: Request = { body: undefined, query: {} }; // defaults used const created: Request<{ name: string }> = { body: { name: "x" }, query: {} };

The b case is the one people trip over: an async function whose body always throws still has a return type (Promise<never>), so T is inferred as never, not left to the default. A default applies when the parameter truly has no inference site — a parameter that only appears in the return type, for instance:

typescript
declare function load<T = string>(): Promise<T>; const s = await load(); // string, from the default const n = await load<number>(); // number

2. Defaults referencing earlier parameters

typescript
type Form<T, K extends keyof T = keyof T> = { values: T; touched: Record<K, boolean>; }; interface Login { email: string; password: string } type LoginForm = Form<Login>; // touched: Record<"email" | "password", boolean> type EmailOnlyForm = Form<Login, "email">; // touched: Record<"email", boolean> function pick<T, K extends keyof T = keyof T>(obj: T, ...keys: K[]): Pick<T, K> { const out = {} as Pick<T, K>; for (const key of keys) out[key] = obj[key]; return out; }

K extends keyof T = keyof T is the standard way to express "any key by default, a subset when asked" and appears in every library that has a pick-like helper. Reversing the order (<K extends keyof T = keyof T, T>) is TS2744: Type parameter defaults can only reference previously declared type parameters, because the name T is not in scope yet.

The constraint and the default are separate: K extends keyof T constrains what K may be, and = keyof T supplies a value. A default that is not assignable to its own constraint fails on the declaration — type X<T extends string = number> is TS2344 before any call is written, which is the compiler refusing a generic that could never instantiate.

3. Defaults and constraints together in classes

typescript
type Entity = { id: string }; abstract class Repository<T extends Entity = Entity> { abstract findById(id: string): T | undefined; abstract save(entity: T): void; } class UserRepo extends Repository<{ id: string; email: string }> { findById(id: string) { return undefined; } save(entity: { id: string; email: string }) {} } class Untyped extends Repository { findById(id: string) { return undefined; } // T = Entity save(entity: Entity) {} }

The default Entity satisfies the constraint extends Entity, so extends Repository without an argument is legal and yields Repository<Entity>. A default that widens the constraint instead of narrowing it cannot work: T extends Entity = unknown fails, because unknown is not assignable to Entity.

Classes add one wrinkle: the type argument is fixed by the constructor call or the extends clause, and there is no partial override.

typescript
class Store<K = string, V = unknown> { private map = new Map<K, V>(); } new Store(); // Store<string, unknown> new Store<number>(); // Store<number, unknown> // new Store<number, string>(); // Store<number, string> // new Store<, string>(); // syntax error

To override only V, the caller must spell out K as well, which is why libraries with several interlocking parameters order them so the most-overridden one comes last.

4. Defaults as a non-breaking API change

typescript
// v1 export function request<T>(url: string): Promise<T>; // v2: add a response-shape parameter with a default export function request<T, R = T>(url: string): Promise<R>; // v3: add an error parameter with a default, keeping existing calls valid export function request<T, R = T, E = Error>(url: string): Promise<R>;

Each added parameter with a default keeps every existing call site compiling, and existing explicit calls (request<Data>(url)) still resolve because the omitted trailing parameters come from their defaults. Removing a default or adding a required parameter is the breaking change; TS2558: Expected 0 type arguments, but got 1 and TS2314: Generic type 'X' requires 2 type arguments are the errors consumers see when that happens. The reverse direction — turning a required parameter into a defaulted one — is safe and is the migration path for libraries that shipped too many required generics.

typescript
// A default that encodes the previous behavior: type Params<P extends Record<string, string> = Record<string, never>> = { path: P }; type NoParams = Params; // { path: Record<string, never> } type WithParams = Params<{ id: string }>; // { path: { id: string } }

Record<string, never> is a useful default for "no parameters" because it accepts an empty object literal and rejects any property, where {} and unknown would accept anything.

5. Where the default is not used at all

typescript
// A default on a parameter that is inferred from a callback's return type. function tap<T = never>(fn: () => T): T { return fn(); } const r = tap(() => 1); // T = number const n = tap(() => undefined); // T = undefined, not never // A default that the constraint overrides via inference from a later parameter. function identity<T = string, U extends T = T>(value: U): T { return value; } const v = identity(1); // T = number (inferred from U), U = number

The first case shows that a callback always provides an inference site, so the default is dead code for every well-typed call — it only matters for tap() with no argument, which is an arity error anyway. The second shows inference flowing backwards through a constraint: U extends T = T gives U a default that refers to T, and when U is inferred from the argument, T is inferred from U through the constraint, so the default for T never applies. Defaults written this way are documentation more than logic, and they are the source of surprising hover types.

Common mistakes and compiler errors

Error or symptomCauseFix
TS2344: Type 'X' does not satisfy the constraint 'Y'the default violates the constraintchoose a default that narrows within the constraint
TS2744: Type parameter defaults can only reference previously declared type parametersa default refers to a parameter declared laterreorder the parameters
TS2706: Required type parameters may not follow optional type parametersa defaulted parameter precedes a required onemove defaults to the end
TS2314: Generic type 'X' requires N type argument(s)the type has no defaults and none were suppliedsupply the argument, or add a default
TS2707: Generic type 'X' requires between N and M type argumentsa partial list was givensupply all required arguments
TS2558: Expected 0 type arguments, but got 1type arguments passed to a non-generic callremove them, or make it generic
A default seems ignoredan inference site exists and produced a typemake the parameter non-inferrable, or accept the inference
Return type is unknown where a default was expectedthe default is on a different parametercheck that the parameter is the one appearing in the return type
new Store<number>() sets the wrong parameterpositional type argumentsreorder so the most-used parameter comes first
Adding a generic breaks consumersthe new parameter has no defaultadd one

Defaults are an interface decision before they are a typing tool: they decide what a caller who writes nothing gets, and that shape is what most call sites will live with. The two rules that prevent the common failures are to put every defaulted parameter after every required one, and to make the default the narrowest useful type — Record<string, never> over {}, never over any, a concrete model over unknown — because a default is the type a caller gets without thinking, and it will be the type they keep for as long as the code compiles.

Try matching browser tools

All tools

Small utilities that fit TypeScript work — they run entirely in this browser tab, so nothing you paste leaves your device.

All TypeScript guides

More in TypeScript

All TypeScript guides

The guides filed next to this one in TypeScript, in library order.