Typing the DOM

What TypeScript knows about your page

A product card has a quantity box, <input id="quantity">, holding 2. Every example in this lesson runs on that card. Your code finds the box and reads what's in it:

1const quantityBox = document.querySelector("#quantity");2//    ^?3console.log(quantityBox.value);

Line 1 looks the box up with document.querySelector, which gives back the first element that matches a CSS selector (the Walking & searching the DOM lesson covers it). The query on line 2 shows the type TypeScript gives the result: Element | null. Line 3 reads value, and TypeScript marks it twice, on purpose:

• 'quantityBox' is possibly 'null' means the lookup may have found nothing. On a page without the box, line 3 would throw a TypeError.
• Property 'value' does not exist on type 'Element' means TypeScript only knows it's "some element", and most elements, like a paragraph, have no value.

On this page the code still prints 2. TypeScript isn't wrong about the page; it has never seen it. It doesn't read your HTML. Everything it knows about the page comes from the DOM's type definitions, a file called lib.dom.d.ts that ships with TypeScript, and from the lookup itself. Here the lookup only says "#quantity", which could be any element.

Ask for a tag name instead, and check for null, and both errors go:

1const quantityBox = document.querySelector("input");2//    ^?3if (quantityBox) {4  console.log(quantityBox.value);5}

Line 1 asks for "input", a tag name, and the query on line 2 shows TypeScript now knows the kind: HTMLInputElement | null. Line 3 checks that the box was found, so line 4 may read value. It prints 2.

Element, HTMLElement, and HTMLInputElement

The DOM's types form a family. Each one is a more specific kind of the one above it, and has everything that one has, plus more. (In JavaScript these are real classes; Node properties & contents shows them.) Here are the ones you'll meet most:

The more specific the type, the more TypeScript lets you use. Try it on a function that shows a field. The buttons change the type of its parameter, field, on line 1:

1function showField(field: Element) {2  console.log(field.id);3  console.log(field.hidden);4  console.log(field.value);5}6 7const box = document.createElement("input");8box.id = "quantity";9box.value = "2";10showField(box);

With Element, lines 3 and 4 are marked: not every element can be hidden or has a value. HTMLElement allows hidden, so only line 4 is left. HTMLInputElement allows all three. Line 7 makes a real input box with document.createElement, and line 10 passes it in. That's allowed with every button, because an input box is an HTMLElement and an Element too. It prints quantity, false, and 2 each time: the type only changes what TypeScript allows.

The table below lists the common types. Read each row as: the type, which elements it covers, and what it adds to the one above.

How querySelector picks a type

TypeScript's DOM types include a list that pairs each tag name with its type: "input" with HTMLInputElement, "button" with HTMLButtonElement, and so on. When your selector is exactly a tag name, querySelector uses that list. Otherwise it falls back to Element:

1const search = document.querySelector("input");2//    ^?3const plus = document.querySelector("button");4//    ^?5const total = document.querySelector(".total");6//    ^?7const quantity = document.getElementById("quantity");8//    ^?

Line 1's tag name gives HTMLInputElement | null, and line 3's gives HTMLButtonElement | null. Line 5 uses a class, .total, which could be on any element, so it gets Element | null. Line 7 uses getElementById, which TypeScript's DOM types say gives HTMLElement | null for any id. Now try your own selectors. The query on line 2 shows the type as you type:

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

#quantity and input#quantity find the very same box as input, but get Element | null: only a selector that is exactly a tag name counts. svg is a tag name from the list of SVG tags, so it gets SVGSVGElement | null, though this page has no picture to find.

querySelectorAll finds every match, and gives back a list called a NodeList:

1const prices = document.querySelectorAll(".price");2//    ^?3const boxes = document.querySelectorAll("input");4//    ^?5console.log(prices.length, boxes.length);

The query on line 2 shows NodeListOf<Element>: a list of elements, from a class. Line 4 shows NodeListOf<HTMLInputElement>, from a tag name. Neither type has | null: when nothing matches, you get an empty list. Line 5 prints 2 3, two prices and three input boxes on this page.

When you know the kind and the selector can't say it, you can name it yourself in angle brackets. This is a type argument, the same idea as in Generic functions:

1const quantityBox = document.querySelector<HTMLInputElement>("#quantity");2//    ^?3if (quantityBox) {4  console.log(quantityBox.valueAsNumber + 1);5}

Line 1 passes HTMLInputElement between < and >, and the query on line 2 shows HTMLInputElement | null. The | null stays, so line 3 still checks. Line 4 reads valueAsNumber, which a number box has: its contents as a number, not as text. It prints 3. A type argument is a claim, like as in Type assertions: TypeScript trusts it, and nothing checks it while the page runs.

The table below sums up the lookups. Read each row as: what you write, the type TypeScript gives, and why.

Handling null from a lookup

Every querySelector and getElementById can give null, because a page might not have the element. TypeScript makes you decide what happens then. There are four common ways, and null and undefined introduced most of them. Here they are on the coupon box, after No check, which skips the decision. Pick a way, then untick the checkbox to take the box off the page:

1const couponBox = document.querySelector<HTMLInputElement>("#coupon");2console.log(couponBox.value);

No check is marked: 'couponBox' is possibly 'null'. Without the box it throws a TypeError. if check and ?. and ?? keep working without the box: one runs the else, the other prints a fallback. Throw early stops with a message that says what's wrong. ! after the lookup silences TypeScript and fails just like No check, so it hides the warning without fixing anything.

All of these trust the type argument about what kind of element it is. To check the kind for real, use instanceof, which asks the element itself while the page runs (in & instanceof covers it). It handles null too:

1const field = document.querySelector("#coupon");2if (field instanceof HTMLInputElement) {3  console.log(field.value);4  //          ^?5} else {6  console.log("No coupon box here");7}

Line 1 has no type argument, so field is Element | null. Line 2 asks whether it really is an input box. Inside the if, the query on line 4 shows TypeScript agrees: const field: HTMLInputElement. Line 3 prints tea10. If the page had no coupon box, or #coupon were a paragraph, line 6 would run instead, because null instanceof HTMLInputElement is false.

The table below compares the ways. Read each row as: what you write, what happens when the element is missing, and when to use it.

Creating elements

document.createElement makes a new element (Creating & changing elements covers it). It uses the same list of tag names, and it never gives null, because a new element always exists:

1const list = document.createElement("ul");2//    ^?3const item = document.createElement("li");4//    ^?5item.textContent = "Green tea";6item.dataset.price = "4";7list.append(item);8console.log(list.outerHTML);

The query on line 2 shows HTMLUListElement, a <ul> list, and line 4 shows HTMLLIElement, a list item. Line 5 sets the item's text. Line 6 stores the price in dataset, which holds an element's data- attributes (Attributes & properties covers them). Line 7 puts the item in the list, and line 8 prints <ul><li data-price="4">Green tea</li></ul>.

Two details trip people up. Both are in this example:

1const badge = document.createElement("span");2badge.dataset.count = 3;3const price = badge.dataset.price;4//    ^?5const typo = document.createElement("buton");6//    ^?

Line 2 stores the number 3 in dataset, and TypeScript marks it on purpose: Type 'number' is not assignable to type 'string'. Attributes are always text, so dataset only holds strings. Line 3 reads a price that was never set, and the query on line 4 shows string | undefined. Line 5 misspells "button". That's not an error, because a page may make its own tags, like cart-badge. The query on line 6 gives the clue: HTMLElement, not HTMLButtonElement.

A quantity stepper on a product card

Put it together. The card has a plus button that adds one to the quantity and updates the total, at $4 a box. The code looks up three elements, checks them all once, and then uses them freely:

1const quantityBox = document.querySelector<HTMLInputElement>("#quantity");2const plusButton = document.querySelector(".plus");3//    ^?4const totalText = document.querySelector("#total");5 6if (!quantityBox || !(plusButton instanceof HTMLButtonElement) || !totalText) {7  throw new Error("The product card is missing a part");8}9 10plusButton.addEventListener("click", () => {11  quantityBox.valueAsNumber += 1;12  totalText.textContent = `$${quantityBox.valueAsNumber * 4}`;13});14 15plusButton.click();16console.log(quantityBox.value, totalText.textContent);

Line 1 names the kind with a type argument. Line 2 looks up the button by class, so the query on line 3 shows Element | null. Line 4 finds the total. Line 6 checks all three at once: the box and the total must be there, and the button must really be a <button>. If not, line 7 stops with a clear message. After line 8, TypeScript knows all three are there, even inside the function on lines 10 to 13, which runs on each click. Line 11 adds one to the number in the box, and line 12 writes the new total. Line 15 clicks the button once from code, and line 16 prints 3 $12. The next lesson types the click event itself.

Common mix-ups

The most expensive mix-up is treating a type argument as a check. Here the claim is wrong:

1const totalBox = document.querySelector<HTMLInputElement>("#total");2//    ^?3if (totalBox) {4  console.log(totalBox.value);5}

Line 1 says #total is an input box. The query on line 2 shows TypeScript believes it, and there are no errors. But on this page #total is a paragraph, which has no value, so line 4 prints undefined. Nothing warned you. instanceof HTMLInputElement would have caught it.

• "TypeScript reads my HTML." No. It only sees the lookup in your code. The page can have an input box with that id, and the type is still Element | null.
• "querySelector<HTMLInputElement> checks the element." No. It's a claim, removed with the other types. Only instanceof checks while the page runs.
• "An element on my page can't be null." No. The same script often runs on pages without it, or before the element exists. TypeScript can't tell, so every lookup includes null.
• "input.quantity is a tag name, so I get HTMLInputElement." No. Only a selector that is exactly a tag name counts. Anything more gives Element.
• "querySelectorAll needs a null check." No. It gives an empty list when nothing matches.
• "A misspelled tag in createElement is an error." No. Any name is allowed. The type HTMLElement instead of the one you expected is the clue.

Practice exercises

Every exercise runs on this lesson's product card. 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 total = document.querySelector(".total");2console.log(total?.textContent);

1const total = document.querySelector(".total");2//    ^?3console.log(total?.textContent);

1const sizePicker = document.createElement("select");2console.log(sizePicker.tagName);

1const sizePicker = document.createElement("select");2//    ^?3console.log(sizePicker.tagName);

1const emailBox = document.querySelector("#email");2console.log(emailBox.value.split("@")[1]);

1const emailBox = document.querySelector<HTMLInputElement>("#email");2console.log(emailBox?.value.split("@")[1]);

1const giftNote = document.querySelector<HTMLInputElement>("#gift-note")!;2console.log(giftNote.value);

1const giftNote = document.querySelector<HTMLInputElement>("#gift-note");2console.log(giftNote?.value ?? "No gift note");

1const totalBox = document.querySelector<HTMLInputElement>("#total");2console.log(totalBox?.value);

1const totalBox = document.querySelector("#total");2if (totalBox instanceof HTMLInputElement) {3  console.log(totalBox.value);4} else {5  console.log("#total isn't an input box");6}

1const list = document.createElement("ul");2const item: HTMLDivElement = document.createElement("li");3item.textContent = "Cake";4item.dataset.price = 4;5list.append(item);6console.log(list.outerHTML);

1const list = document.createElement("ul");2const item: HTMLLIElement = document.createElement("li");3item.textContent = "Cake";4item.dataset.price = "4";5list.append(item);6console.log(list.outerHTML);

Check your understanding

For each question, ask what TypeScript can know from the code alone, and what the page has when the code runs. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• TypeScript doesn't read your HTML. It types each lookup from the lookup itself, using the DOM's type definitions.
• Element, HTMLElement, and HTMLInputElement go from general to specific. The more specific the type, the more you can use.
• A selector that is exactly a tag name gives that tag's type. Anything else gives Element, and getElementById gives HTMLElement.
• querySelector and getElementById can give null; querySelectorAll gives a list and createElement gives a new element, so neither can.
• A type argument, like as and !, is a claim TypeScript trusts. instanceof checks for real.
• dataset holds only strings, and a misspelled tag in createElement quietly gives HTMLElement.

Coming next: Typing events. It types what your handlers receive: MouseEvent, KeyboardEvent, and the difference between event.target and event.currentTarget.