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.

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), notanyand 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
// 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:
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
| Situation | Without a default | With a default |
|---|---|---|
| Argument provides an inference site | inferred type | inferred type; default ignored |
| No inference site, no type argument | unknown | the default |
| Explicit type argument given | used | used; default ignored |
| Partial type argument list | not possible | trailing defaults may be omitted |
| Constraint violated by the default | n/a | TS2344 on the declaration |
Caller overrides with undefined | not applicable | not 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
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:
declare function load<T = string>(): Promise<T>;
const s = await load(); // string, from the default
const n = await load<number>(); // number2. Defaults referencing earlier parameters
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
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.
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 errorTo 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
// 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.
// 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
// 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 = numberThe 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 symptom | Cause | Fix |
|---|---|---|
TS2344: Type 'X' does not satisfy the constraint 'Y' | the default violates the constraint | choose a default that narrows within the constraint |
TS2744: Type parameter defaults can only reference previously declared type parameters | a default refers to a parameter declared later | reorder the parameters |
TS2706: Required type parameters may not follow optional type parameters | a defaulted parameter precedes a required one | move defaults to the end |
TS2314: Generic type 'X' requires N type argument(s) | the type has no defaults and none were supplied | supply the argument, or add a default |
TS2707: Generic type 'X' requires between N and M type arguments | a partial list was given | supply all required arguments |
TS2558: Expected 0 type arguments, but got 1 | type arguments passed to a non-generic call | remove them, or make it generic |
| A default seems ignored | an inference site exists and produced a type | make the parameter non-inferrable, or accept the inference |
Return type is unknown where a default was expected | the default is on a different parameter | check that the parameter is the one appearing in the return type |
new Store<number>() sets the wrong parameter | positional type arguments | reorder so the most-used parameter comes first |
| Adding a generic breaks consumers | the new parameter has no default | add 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 toolsSmall utilities that fit TypeScript work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related TypeScript guides
All TypeScript guidesTypeScript Branded Types: Nominal Typing, Type Tags, and Validation
How a phantom property makes two strings incompatible, unique symbol brands, unit-typed numbers, and the places where a brand quietly disappears.
TypeScript Ambient Declarations: .d.ts Files, declare, and declare global
How declare and .d.ts files describe runtime values, wildcard modules for assets, declare global with var, and module augmentation of third-party types.
TypeScript Discriminated Unions: Exhaustiveness Checking and the never Type
Why the discriminant must be a literal, how never closes an exhaustive switch, and the duplicate-discriminant bug that lets a missing case compile.
TypeScript Enums: Numeric, String, const Enums, and Alternatives
How each enum form compiles, why numeric enums emit a reverse mapping, what const enums cost under per-file transpilation, and how an as const object replaces them.
More in TypeScript
All TypeScript guidesThe guides filed next to this one in TypeScript, in library order.