Course contentsShow
← TypeScript
Lesson 222 of 1,7965. Type Narrowing FundamentalsFree lesson

Basic Type Predicate Syntax

Writing functions with `parameterName is Type` return signatures to create custom type guards.

Basic Type Predicate Syntax

What you'll learn: How to write custom functions that tell TypeScript "this value is definitely this specific type" using the special is keyword.


The Problem Type Predicates Solve

You've learned how typeof, instanceof, and in help TypeScript narrow types. But what if you need more complex logic that those operators can't express? That's where type predicates come in—they let you create your own custom type-checking functions that TypeScript understands and trusts.

The Magic Return Signature

A type predicate uses a special return type syntax:

function isString(value: unknown): value is string {
  return typeof value === 'string';
}

Notice value is string instead of just boolean. This tells TypeScript: "If this function returns true, then the parameter value is definitely a string."

How It Works

function processValue(input: string | number) {
  if (isString(input)) {
    // TypeScript knows input is string here
    console.log(input.toUpperCase());
  } else {
    // TypeScript knows input is number here
    console.log(input.toFixed(2));
  }
}

Without the is keyword, TypeScript would only see isString returning a boolean—it wouldn't connect that result to narrowing the type.

The Syntax Pattern

function isSomeType(param: WiderType): param is NarrowerType {
  // your runtime check logic
  return /* boolean expression */;
}
  • param: Must match your parameter name exactly
  • is: The keyword that makes this a type predicate
  • NarrowerType: The specific type you're confirming

Key Takeaway: Type predicates use parameterName is Type return signatures to create custom type guards that TypeScript recognizes during control flow analysis, enabling you to narrow types with your own logic.