null, undefined & strictNullChecks

A value that might not be there

A search page reads its web address to see what the shopper asked for. The address ?q=tea asks for tea, with no sort order. Here is plain JavaScript asking for the sort order anyway:

const params = new URLSearchParams("?q=tea");
const sort = params.get("sort");
console.log(sort.toUpperCase());

Line 1 reads the part of the address after ? with URLSearchParams (the URL objects lesson covers it). Line 2 asks for sort. The address has no sort, so get gives back null, JavaScript's value for "nothing here". Line 3 calls .toUpperCase() on null, and the code stops with TypeError: Cannot read properties of null. Nothing warned you before it ran.

Here is the same code in TypeScript:

1const params = new URLSearchParams("?q=tea");2const sort = params.get("sort");3//    ^?4console.log(sort.toUpperCase());

The query on line 3 shows the type TypeScript gives sort: string | null. The | means "or", so sort is a string or null. TypeScript marks line 4, on purpose here, because it's the bug:

• 'sort' is possibly 'null' means "this value might be null, and you're using it as if it can't be".
• ts(18047) is the error's number. A value that might be undefined gets a sister error, ts(18048), which you'll meet below.

strictNullChecks: null gets its own type

Whether TypeScript keeps null in a type depends on one setting, strictNullChecks. Settings like this live in a project's tsconfig.json file. Turning on strict turns it on, along with a group of other checks, and a new project made with tsc --init has strict on:

{
  "compilerOptions": {
    "strict": true
  }
}

Line 3 turns on strict, and with it strictNullChecks. Every example in this lesson is checked with it on, unless it says otherwise. Switch it off and on for the overview's code:

1const params = new URLSearchParams("?q=tea");2const sort = params.get("sort");3//    ^?4console.log(sort.toUpperCase());

With the flag on, the query on line 3 shows string | null, and line 4 has its error. With the flag off, the query shows only string, and the error is gone. The code throws the same TypeError either way: turning the flag off removes the warning, not the bug. TypeScript's own documentation recommends keeping it on.

With the flag on, null and undefined are types of their own. A plain string can't hold either one, so a type has to say when something may be missing:

1let nickname: string = null;2let middleName: string | null = null;3let lastName: string | null = undefined;

Line 1 says nickname is a string and gives it null. TypeScript says Type 'null' is not assignable to type 'string': null isn't allowed in a plain string. Line 2 says middleName is string | null, so null is fine. Line 3 gives that same type undefined and gets Type 'undefined' is not assignable to type 'string | null'. So null and undefined are two different types: a type that allows one doesn't allow the other.

You rarely write | null yourself at first. The browser's own functions, and your own data types, already say it. Read the queries, or point at each name:

1type CartItem = { name: string; price: number };2const cart: CartItem[] = [{ name: "Tea", price: 3 }];3 4const searchBox = document.querySelector("input");5//    ^?6const theme = localStorage.getItem("theme");7//    ^?8const cake = cart.find((item) => item.name === "Cake");9//    ^?

Line 4 asks the page for an <input> element, and the query on line 5 shows HTMLInputElement | null. Line 6 reads a saved setting from the browser's storage (see Web storage), and the query on line 7 shows string | null. Line 8 searches the cart with find (see Searching arrays), and the query on line 9 shows CartItem | undefined. This example only shows types, because localStorage needs a real site, so it has no Edit & run.

The table lists where missing values come from in everyday frontend code. Read each row as: this code, the type TypeScript gives it, and when the value is missing.

To use a value like this, check it first:

1const params = new URLSearchParams("?q=tea");2const sort = params.get("sort");3 4if (sort !== null) {5  console.log(sort.toUpperCase());6  //          ^?7} else {8  console.log("No sort chosen");9}

Line 4 checks that sort isn't null. Inside the braces, the query on line 6 shows const sort: string: TypeScript knows the check passed, so line 5 is fine. Line 8 runs when sort is null, and here it prints No sort chosen. This is the narrowing you met in Union types: a check makes the type smaller. The Narrowing lesson covers it in depth.

Reading safely with ?. and ??

JavaScript has two operators for values that may be missing (the Nullish coalescing and optional chaining lesson covers them):

• ?. reads a property only when the value before it isn't null or undefined. Otherwise it stops and gives undefined.
• ?? gives a backup when the value on its left is null or undefined.

TypeScript understands both and works out the types they give. Here is a user profile where the address is optional:

1type Profile = { name: string; address?: { city: string } };2 3const asha: Profile = { name: "Asha" };4console.log(asha.address.city);

Line 1 describes a Profile. The ? in address?: makes the property optional: a profile may leave it out. Line 3 makes Asha's profile with no address. Line 4 reads asha.address.city, and TypeScript says 'asha.address' is possibly 'undefined'. It's right: when this runs, it throws a TypeError.

1type Profile = { name: string; address?: { city: string } };2 3const asha: Profile = { name: "Asha" };4const city = asha.address?.city;5//    ^?6const label = city ?? "No city yet";7//    ^?8console.log(label);

Line 4 reads with ?. instead. Asha has no address, so ?. stops and gives undefined. The query on line 5 shows const city: string | undefined: TypeScript added undefined to the type, because ?. can give it. Line 6 uses ?? to swap a missing city for "No city yet". The query on line 7 shows const label: string: the backup takes the place of undefined, so the type has none left. Line 8 prints No city yet.

?? isn't the same as ||. || also replaces 0, "", and false, which can be real values. TypeScript can't catch this mix-up, because both give a number here:

1type Settings = { fontSize?: number };2 3const settings: Settings = { fontSize: 0 };4const withOr = settings.fontSize || 16;5const withNullish = settings.fontSize ?? 16;6//    ^?7console.log(withOr, withNullish);

Line 3 sets a font size of 0. Line 4 uses ||, which treats 0 as missing and gives 16. Line 5 uses ??, which keeps 0. The query on line 6 shows const withNullish: number, and withOr is a number too, so there's no error either way. Line 7 prints 16 0. When 0 or empty text is a real value, use ??.

The non-null assertion !

Sometimes you know more than TypeScript. A search page's own HTML has a search box, so asking for it always finds one. But TypeScript can't see your HTML:

1const searchBox = document.querySelector("input");2//    ^?3console.log(searchBox.value);

Line 1 asks the page for its <input>. The query on line 2 shows const searchBox: HTMLInputElement | null, because some page might have none. Line 3 reads the box's value and gets 'searchBox' is possibly 'null'. This page does have a box, with tea typed in it, so when it runs the code prints tea anyway.

A ! right after a value is the non-null assertion. It tells TypeScript: "this isn't null or undefined, trust me".

1const searchBox = document.querySelector("input")!;2//    ^?3console.log(searchBox.value);

Line 1 ends with !. The query on line 2 shows const searchBox: HTMLInputElement: null is gone from the type. Line 3 has no error and prints tea.

The ! is only a promise. Nothing checks it when the code runs. Make the same promise about the sort order, which really is missing:

1const params = new URLSearchParams("?q=tea");2const sort = params.get("sort")!;3//    ^?4console.log(sort.toUpperCase());

Line 2 ends with !, so the query on line 3 shows const sort: string, and line 4 has no error. When it runs, sort is null, and line 4 throws the same TypeError as the overview. Here is what the browser gets:

const params = new URLSearchParams("?q=tea");
const sort = params.get("sort");
console.log(sort.toUpperCase());

It's the overview's JavaScript, line for line. The ! was removed with the types, so it couldn't stop anything. Use ! only when you're sure, like an element your own HTML always has. When you're not sure, check the value or give a backup.

The table compares four ways to handle a value that might be missing. Read each row as: what you write, what TypeScript does, and what happens when the value really is missing.

Optional parameters vs undefined

A function's parameter can be missing too, when a call leaves it out (see Parameters). A ? after a parameter's name makes it optional. That's different from a parameter whose type includes undefined. Swap line 1 between four ways of writing the name parameter, and watch lines 8 and 9:

1function greet(name?: string) {2  const shown = name ?? "guest";3  //            ^?4  return `Hello, ${shown}`;5}6 7console.log(greet("Asha"));8console.log(greet());9console.log(greet(undefined));

Line 7 passes "Asha", line 8 passes nothing, and line 9 passes undefined. With name?: string, all three are fine, and the query on line 3 shows string | undefined. With name: string | undefined, line 8 gets Expected 1 arguments, but got 0: the name must be passed, even if it's undefined. With name: string, line 9 is marked too. With name = "guest", a default value, every call is fine again, and inside the function name is a plain string.

The console output never changes: Hello, Asha, then Hello, guest twice. When the code runs, a left-out argument is undefined either way. Only what TypeScript allows changes.

The table sums up the four. Read each row as: what you write, whether a call can leave the name out, and the type of name inside the function.

Object properties work the same way. nickname?: may be left out of the object, but bio: string | undefined must be written, even when its value is undefined:

1type Profile = { name: string; nickname?: string; bio: string | undefined };2 3const asha: Profile = { name: "Asha", bio: undefined };4const ravi: Profile = { name: "Ravi", nickname: "Rav" };

Line 1 describes a Profile with an optional nickname and a bio that may be undefined. Line 3 leaves out the nickname and writes bio: undefined, which is fine. Line 4 writes a nickname but leaves out bio, and gets an error that starts Property 'bio' is missing. In plain words: the object has no bio, and the type says it must have one.

A search page that handles a missing value

Back to the search page. The playground has this lesson's five ways to handle sort on line 4, and two page addresses on line 1: one with no sort, and one with sort=price. Try each way with each address.

1const params = new URLSearchParams("?q=tea");2const sort = params.get("sort");3 4console.log(sort.toUpperCase());

With ?q=tea&sort=price, every way prints PRICE, even Use it as is, which still has its error. TypeScript checks every value sort could have, not just the one this address gives. With ?q=tea, Use it as is and Promise with ! both throw a TypeError. Check for null prints No sort chosen, Backup with ?? prints RELEVANCE, and Read with ?. prints undefined, which a shopper shouldn't see. The check and the ?? backup handle both addresses well.

Real data mixes all of this. A profile from a server may leave out a nickname, have no picture yet, and have no address:

1type Profile = {2  name: string;3  nickname?: string;4  avatarUrl: string | null;5  address?: { city: string };6};7 8function profileLine(user: Profile) {9  const shown = user.nickname ?? user.name;10  const city = user.address?.city ?? "somewhere";11  const avatar = user.avatarUrl ?? "/default-avatar.png";12  return `${shown} from ${city} (${avatar})`;13}14 15console.log(profileLine({ name: "Asha", avatarUrl: null }));16console.log(profileLine({ name: "Ravi", nickname: "Rav", avatarUrl: "/ravi.png", address: { city: "Pune" } }));

Lines 1 to 6 describe the profile: nickname and address are optional, and avatarUrl is a string or null. Line 9 shows the nickname, or the name when there's no nickname. Line 10 reads the city with ?. and falls back to "somewhere". Line 11 falls back to a default picture. Line 15 prints Asha from somewhere (/default-avatar.png), and line 16 prints Rav from Pune (/ravi.png). There's no ! anywhere: every missing value has a plan.

Common mix-ups

Both null and undefined mean "missing" to you, but TypeScript keeps them apart:

1function findNickname(name: string): string | null {2  return name === "Ravi" ? "Rav" : undefined;3}

Line 1 says findNickname gives back a string or null. Line 2 gives back undefined when the name isn't Ravi, and TypeScript says Type 'undefined' is not assignable to type 'string | null'. Give back null instead, or write the type as string | null | undefined.

• "null and undefined are the same type." No. They're two types. string | null doesn't accept undefined, and string | undefined doesn't accept null.
• "The ! checks that the value is there." No. It's removed with the types. If the value is missing, the code throws the same TypeError as with no check at all.
• "Turning strictNullChecks off fixes the error." No. It hides the warning. The value is still null when the code runs.
• "?. handles the missing value for me." No. It gives undefined instead of throwing. You still decide what to show, often with ??.
• "?? and || do the same thing." No. || also replaces 0, "", and false. ?? replaces only null and undefined.
• "name?: string and name: string | undefined mean the same." No. Both give name the type string | undefined inside, but only the first lets a call leave it out.

Practice exercises

Each exercise is TypeScript. When you fix code, press Edit & run on the starter code: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

1const couponBox = document.querySelector("#coupon");

1const couponBox = document.querySelector("#coupon");2//    ^?

type User = { name: string; nickname?: string };

const asha: User = { name: "Asha" };
console.log(asha.nickname.toUpperCase());

1type User = { name: string; nickname?: string };2 3const asha: User = { name: "Asha" };4console.log(asha.nickname?.toUpperCase() ?? asha.name);

1type Settings = { theme?: string };2 3const settings: Settings = {};4const theme: string = settings.theme;5console.log(theme);

1type Settings = { theme?: string };2 3const settings: Settings = {};4const theme: string = settings.theme ?? "light";5console.log(theme);

1function priceLabel(price: number, currency: string) {2  return `${price} ${currency}`;3}4 5console.log(priceLabel(3, "USD"));6console.log(priceLabel(3));

1function priceLabel(price: number, currency = "EUR") {2  return `${price} ${currency}`;3}4 5console.log(priceLabel(3, "USD"));6console.log(priceLabel(3));

1const totalBox = document.querySelector("#total")!;2totalBox.textContent = "$7";3console.log("Total shown");

1const totalBox = document.querySelector("#total");2if (totalBox !== null) {3  totalBox.textContent = "$7";4  console.log("Total shown");5} else {6  console.log("No total on this page");7}

1type Profile = { name: string; address?: { city: string | null } };2 3function cityLabel(user: Profile) {4  return user.address.city.toUpperCase();5}6 7console.log(cityLabel({ name: "Asha", address: { city: "Pune" } }));8console.log(cityLabel({ name: "Ravi", address: { city: null } }));9console.log(cityLabel({ name: "Mei" }));

1type Profile = { name: string; address?: { city: string | null } };2 3function cityLabel(user: Profile) {4  return user.address?.city?.toUpperCase() ?? "Unknown city";5}6 7console.log(cityLabel({ name: "Asha", address: { city: "Pune" } }));8console.log(cityLabel({ name: "Ravi", address: { city: null } }));9console.log(cityLabel({ name: "Mei" }));

Check your understanding

For each question, keep two moments apart: what TypeScript says before the code runs, and what the code does when it runs. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A value that might be missing has null or undefined in its type, like string | null.
• With strictNullChecks on (part of strict), TypeScript makes you handle the missing case before you use the value. Off, the bug is still there; only the warning is gone.
• null and undefined are two different types. Browser functions like querySelector give null; find and optional properties give undefined.
• Check with if (x !== null), read with ?., and give a backup with ??. TypeScript follows each one.
• ! removes null and undefined from the type and checks nothing. Use it only when you're sure.
• x?: T may be left out; x: T | undefined must be written, even as undefined.

Coming next: Enums. They give a fixed set of choices names, like the sort orders a search page offers, and they're one of the few TypeScript features that still exist when the code runs.