TypeScript null and undefined: Checks, ?. and ?? Operators

With strictNullChecks on (it is part of strict), null and undefined are their own types. A string can never be null; a value that might be missing has to say so in its type, like string | null, and TypeScript makes you handle that case before using the value.

function initials(name: string | null | undefined): string {
  if (name == null) return "?"; // handles both null and undefined
  return name
    .split(" ")
    .map((part) => part[0])
    .join("");
}

console.log(initials("Ada Lovelace")); // AL
console.log(initials(null));           // ?
console.log(initials(undefined));      // ?

After the check, the compiler knows name is a string, so .split is allowed. The rest of this page covers the ways to do that check and the operators that make it short.

strictNullChecks and "Possibly Null" Errors

When a type includes null or undefined, TypeScript refuses to use the value as if it were always there:

// This does not compile: name may be null
function greet(name: string | null) {
  return "Hello, " + name.toUpperCase();
}

console.log(greet("ada"));

index.ts(3,22): error TS18047: 'name' is possibly 'null'.

The undefined version is TS18048, 'x' is possibly 'undefined'. Without strictNullChecks, null and undefined are allowed in every type and this code compiles, then crashes at runtime with a TypeError the first time name is null. That class of bug is the main reason to keep strict on.

Where these types come from in everyday code:

Checking for null and undefined

Every check below narrows the type inside the block. Pick the one that matches what you want to exclude.

function label(value: string | null | undefined): string {
  if (value === undefined) return "undefined";
  if (value === null) return "null";
  return value.toUpperCase(); // value is string here
}

function orNone(value: string | null | undefined): string {
  if (value == null) return "(none)"; // == null matches null AND undefined
  return `"${value}"`;
}

console.log(label(undefined), label(null), label("ok")); // undefined null OK
console.log(orNone(null), orNone(undefined), orNone("")); // (none) (none) ""

== null is the one place where loose equality is idiomatic: it is true for exactly null and undefined, nothing else. A truthiness check would have treated the empty string as missing, which is often a bug.

Optional Chaining: ?.

a?.b reads b if a is not null or undefined, and otherwise stops and returns undefined. The same operator works for indexes, a?.[i], and for calls, fn?.().

interface User {
  name: string;
  address?: { city: string; zip?: string };
  tags?: string[];
  onLogin?: () => string;
}

const ada: User = { name: "Ada", address: { city: "London" }, onLogin: () => "welcome" };
const bob: User = { name: "Bob" };

console.log(ada.address?.city);        // London
console.log(bob.address?.city);        // undefined
console.log(ada.address?.zip?.length); // undefined
console.log(bob.tags?.[0]);            // undefined
console.log(ada.onLogin?.());          // welcome
console.log(bob.onLogin?.());          // undefined

The type of bob.address?.city is string | undefined: optional chaining adds undefined to the result, so you usually pair it with ??. The runtime behavior is plain JavaScript; see optional chaining for the details of short-circuiting.

The Double Question Mark: ??

a ?? b returns a unless it is null or undefined, in which case it returns b. It replaces the older a || b idiom, which also discards 0, "", false and NaN:

function pageSize(input: number | undefined): string {
  const withOr = input || 20;      // 0 is falsy, so it is replaced
  const withNullish = input ?? 20; // only undefined is replaced
  return `${withOr} vs ${withNullish}`;
}

console.log(pageSize(undefined)); // 20 vs 20
console.log(pageSize(0));         // 20 vs 0

const scores = new Map([["Ada", 90]]);
const score: number = scores.get("Linus") ?? 0; // number | undefined becomes number
console.log(score);                             // 0

For types, ?? removes null and undefined from the left side and unions the rest with the right side, which is why scores.get("Linus") ?? 0 can be assigned to a number.

Nullish Assignment: ??=

a ??= b assigns b to a only when a is null or undefined. Its siblings ||= and &&= assign when the left side is falsy or truthy.

interface Options {
  retries?: number;
  label?: string;
}

function withDefaults(opts: Options) {
  opts.retries ??= 3;   // assign only if null or undefined
  opts.label ||= "job"; // assign if falsy, so "" is replaced too
  return opts;
}

console.log(withDefaults({}));                       // { retries: 3, label: 'job' }
console.log(withDefaults({ retries: 0, label: "" })); // { retries: 0, label: 'job' }

retries: 0 survives ??=, while the empty label is replaced by ||=. After opts.retries ??= 3, TypeScript narrows opts.retries to number for the rest of the function.

Optional Properties vs | undefined

nickname?: string and nickname: string | undefined read the same, but they differ in whether the key must exist:

interface WithOptional { nickname?: string }            // key may be missing
interface WithUndefined { nickname: string | undefined } // key must be present

const a: WithOptional = {};
const b: WithUndefined = { nickname: undefined };

// @ts-expect-error: Property 'nickname' is missing in type '{}' but required in type 'WithUndefined'.
const c: WithUndefined = {};

console.log("nickname" in a, "nickname" in b); // false true
console.log(a.nickname === b.nickname);        // true: both read as undefined

Use ? when callers may leave the property out, and | undefined when you want every caller to pass it explicitly, even if the value is undefined. The option exactOptionalPropertyTypes (not part of strict) tightens ? further: nickname?: string then rejects { nickname: undefined } and only accepts a missing key or a string. Optional function parameters (x?: number) behave like optional properties: inside the function x is number | undefined.

null or undefined: Which to Use

TypeScript does not force a choice, but mixing both in one codebase means every check has to handle two cases. A common convention:

• Use undefined (and optional properties) for "not set" in your own types. It is what JavaScript produces by default: missing properties, omitted arguments, find and Map.get misses.
• Accept null where an API gives it to you: JSON has no undefined, String.prototype.match and many DOM methods return null.
• Check with == null when a value might be either.

Array indexing is the one gap: users[5] is typed as the element type even when the index is out of range. The noUncheckedIndexedAccess option (not part of strict) adds | undefined to every index access so the compiler catches that too.