Typing events

The event name picks the event type

A search box on a shop page reacts to key presses. In JavaScript you write a listener with addEventListener, and the browser hands it an event object: facts about what happened, like which key was pressed (the Introduction to events lesson covers this). In TypeScript, that event object has a type, and you usually don't write it:

1const searchBox = document.createElement("input");2 3searchBox.addEventListener("keydown", (event) => {4  //                                   ^?5  console.log(`You pressed ${event.key}`);6});7 8searchBox.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter" }));

Line 1 makes an <input> text box. Line 3 listens for "keydown", the event a key press sends. The answer after the ^? on line 4 shows the type TypeScript gave event: KeyboardEvent. Line 5 reads event.key, the key that was pressed, and every KeyboardEvent has one. Line 8 sends a made-up key press with dispatchEvent, so the listener runs without a real keyboard, and the code prints You pressed Enter.

You never wrote KeyboardEvent. TypeScript worked it out from the name "keydown". Change the name, and the type changes with it:

1const addButton = document.createElement("button");2 3addButton.addEventListener("click", (event) => {4  console.log(`You pressed ${event.key}`);5});6 7addButton.click();

Line 3 listens for "click" on a button. A click is a PointerEvent, and line 4 reads event.key. TypeScript marks it, on purpose here: Property 'key' does not exist on type 'PointerEvent' means "this kind of event has no key". Plain JavaScript would run it and print You pressed undefined when line 7 clicks the button.

Try it yourself: type a different event name on line 2, and watch the answer on line 6 and the list under the code.

1const searchBox = document.createElement("input");2const eventName = "keydown";3 4searchBox.addEventListener(eventName, (event) => {5  console.log(`You pressed ${event.key}`);6  //                         ^?7});8 9searchBox.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter" }));

With keyup, event is still a KeyboardEvent, so there are no errors. click gives a PointerEvent and focus a FocusEvent, and neither has a key. The typo keydwn is the surprise: TypeScript doesn't mark the name. It gives event the plain type Event, which every event shares, and the error shows up on line 5 instead.

How addEventListener knows the type

TypeScript knows the browser through declaration files: files that only describe types, with no code to run. The browser's are in a file called lib.dom.d.ts. Here is the part that matters for events, shortened:

interface GlobalEventHandlersEventMap {
  "click": PointerEvent;
  "focus": FocusEvent;
  "input": Event;
  "keydown": KeyboardEvent;
  "submit": SubmitEvent;
  // … and about 100 more
}

interface HTMLElementEventMap extends ElementEventMap, GlobalEventHandlersEventMap {}

interface HTMLInputElement {
  addEventListener<K extends keyof HTMLElementEventMap>(
    type: K,
    listener: (this: HTMLInputElement, ev: HTMLElementEventMap[K]) => any,
  ): void;
  addEventListener(type: string, listener: EventListenerOrEventListenerObject): void;
}

In plain words, line by line:

1. Lines 1 to 8 are an interface, a list of names and types. Each line pairs an event name with the type of event it sends: "keydown" sends a KeyboardEvent. The real list has more than 100 names.
2. Line 10 makes HTMLElementEventMap, the list for elements, out of that list and a short one, ElementEventMap. window and document have lists of their own, WindowEventMap and DocumentEventMap, built the same way.
3. Lines 13 to 16 are the first version of addEventListener. K is a type parameter: it stands for the name you pass, like "keydown", and must be one of the list's names (the Generic functions lesson explains type parameters). The listener's event is HTMLElementEventMap[K]: the type written next to that name.
4. Line 17 is a second version that takes any text as the name. A name that isn't in the list lands here, and its listener gets a plain Event. That's why keydwn wasn't marked.

It's the same idea that makes document.createElement("input") give an HTMLInputElement: a list pairs each name with a type, and the method looks the name up. So you can look a type up yourself, with the event's name in square brackets. That's handy when you need to write the type down:

1type KeyPress = HTMLElementEventMap["keydown"];2//   ^?3type Click = HTMLElementEventMap["click"];4//   ^?5type Typing = HTMLElementEventMap["input"];6//   ^?7type Send = HTMLElementEventMap["submit"];8//   ^?

Each line gives a name to the type found next to an event name. The answers show "keydown" is a KeyboardEvent (line 2), "click" a PointerEvent (line 4), and "submit" a SubmitEvent (line 8). Line 6 may surprise you: TypeScript lists "input", the event a text box sends as you type, as a plain Event. A text box sends an InputEvent, but a <select> or a checkbox sends a plain Event with the same name, so TypeScript only promises what they all have. You read the new text from the box itself, not from the event.

A PointerEvent is a kind of MouseEvent: it has everything a MouseEvent has, plus facts about the pointer, like whether it was a mouse, a pen, or a finger:

1const addButton = document.createElement("button");2 3addButton.addEventListener("click", (event) => {4  console.log(event.clientX, event.shiftKey, event.pointerType);5});6 7addButton.dispatchEvent(new PointerEvent("click", { clientX: 40, shiftKey: true, pointerType: "mouse" }));

Line 4 reads clientX (how far from the left of the window the click was) and shiftKey (whether Shift was held), which come from MouseEvent, and pointerType, which PointerEvent adds. Line 7 sends a made-up click with those facts, and the code prints 40 true mouse.

The table below lists the events you'll use most. Read each row as: this name, the type the listener gets, and what that type adds.

target and currentTarget

Every event has two properties that point at elements. event.target is where the event began. event.currentTarget is the element whose listener is running. They're different when an event bubbles: a click on an element inside also reaches every element around it (the Bubbling & capturing lesson covers it). Here a list holds a button, and the button holds a span:

1const list = document.createElement("ul");2const addButton = document.createElement("button");3const label = document.createElement("span");4label.textContent = "Add tea";5addButton.append(label);6list.append(addButton);7 8list.addEventListener("click", (event) => {9  console.log(event.target === label);10  //                ^?11  console.log(event.currentTarget === list);12  //                ^?13});14 15label.click();

Lines 1 to 6 build the list, the button, and the span with the words Add tea. Line 8 puts the listener on the list. Line 15 clicks the span. The click begins at the span, so line 9 prints true: the target is the span. The listener is on the list, so line 11 prints true too: the current target is the list.

Now look at the answers on lines 10 and 12. TypeScript gives both the same type, EventTarget | null. An EventTarget is anything that can receive events: an element, but also window or a plain object made with new EventTarget(). TypeScript can't know where a click will begin, so it can't promise a span or a button. The | null covers an event that hasn't been sent yet, whose target is still null.

That type gets in the way when you want something only an element has, like a text box's value. Try four ways of reading what the shopper typed:

1const searchBox = document.createElement("input");2 3searchBox.addEventListener("input", (event) => {4  console.log(`Searching for ${event.target.value}`);5});6 7searchBox.value = "green tea";8searchBox.dispatchEvent(new Event("input"));

event.target gets two errors on line 4, on purpose: it might be null, and an EventTarget has no value. event.currentTarget gets the same two, even though it's always searchBox here: TypeScript's browser types give every event the same currentTarget type. The two fixes work: use the searchBox variable, which is already an HTMLInputElement, or check the target with instanceof (the in & instanceof narrowing lesson explains how the check narrows the type). The code prints Searching for green tea every time: types never change what runs.

You might see event.target as HTMLInputElement in other code. That makes the errors go away without checking anything; the Type assertions lesson explains why it's a promise, not a check. The table below sums up the two properties. Read each row as a question, then the answer for each.

The instanceof check matters most when one listener handles many elements, called event delegation. A menu has one listener, and it finds the button that was clicked:

1const menu = document.createElement("ul");2menu.innerHTML = `<li><button data-product="Tea"><span>Add tea</span></button></li>`;3 4menu.addEventListener("click", (event) => {5  if (!(event.target instanceof Element)) return;6  const button = event.target.closest("button");7  //    ^?8  if (button) console.log(`Added ${button.dataset.product}`);9});10 11menu.querySelector("span")?.click();

Line 2 fills the menu with a button holding a span. Line 4 puts one listener on the menu. Line 5 stops unless the target is an Element; after it, TypeScript knows event.target is one. Line 6 calls closest("button"), which looks from the target outwards for a button. The answer on line 7 shows it gives HTMLButtonElement | null, so line 8 checks for null before it reads the button's data-product. Line 11 clicks the span, and the code prints Added Tea.

Handlers written on their own

So far every listener was written right inside addEventListener, and TypeScript filled in event from the call. That's called contextual typing (the Type annotations & inference lesson covers it). A handler written as a function of its own doesn't get that help:

1function handleKey(event) {2  console.log(`You pressed ${event.key}`);3}4 5const searchBox = document.createElement("input");6searchBox.addEventListener("keydown", handleKey);

Line 1 declares handleKey, and line 6 attaches it. TypeScript checks a function where it's written, before it sees where it's used, so it marks line 1 on purpose: Parameter 'event' implicitly has an 'any' type. That means "nothing says what event is, so it would be any, which turns checking off". Strict mode reports it so you can write the type. Try four types for line 1:

1function handleKey(event: KeyboardEvent) {2  console.log(`You pressed ${event.key}`);3}4 5const searchBox = document.createElement("input");6searchBox.addEventListener("keydown", handleKey);7searchBox.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter" }));

KeyboardEvent fits exactly. Event fits too, because every key press is an Event: a handler may ask for less than it gets. But then line 2 can't read key. MouseEvent asks for more than a key press has, so line 6 gets No overload matches this call. addEventListener has two versions, called overloads (the Function overloads lesson covers them), and the message means the call fits neither. The lines under it say which properties are missing, like clientX.

To write the type without guessing, point at event in an inline listener, or look it up by name as in the last section. A function type can do the lookup once for every key handler:

1type KeyHandler = (event: HTMLElementEventMap["keydown"]) => void;2 3const logKey: KeyHandler = (event) => {4  console.log(`You pressed ${event.key}`);5  //                         ^?6};7 8const searchBox = document.createElement("input");9searchBox.addEventListener("keydown", logKey);10searchBox.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));

Line 1 says a KeyHandler is a function that takes the keydown event and returns nothing. Line 3 gives logKey that type, so its event needs no annotation: the answer on line 5 shows it's a KeyboardEvent. Line 9 attaches it, and line 10's pretend key press prints You pressed Escape.

Custom events and their detail

Your own code can send events too. A CustomEvent carries extra data in a property called detail (the Custom events lesson covers them). In TypeScript, CustomEvent is generic: you write the detail's type in angle brackets.

1type CartAdd = { name: string; quantity: number };2 3const added = new CustomEvent<CartAdd>("cart:add", {4  detail: { name: "Tea", quantity: 2 },5});6 7console.log(added.detail.name);8//                ^?

Line 1 describes what a cart addition holds: a name and a quantity. Line 3 makes a CustomEvent<CartAdd> called "cart:add", and line 4 gives its detail. The answer on line 8 shows detail is a CartAdd, so line 7 prints Tea. TypeScript checks the detail you send against that type:

1type CartAdd = { name: string; quantity: number };2 3const added = new CustomEvent<CartAdd>("cart:add", {4  detail: { name: "Tea", quantity: "2" },5});

Line 4 gives quantity the text "2", so TypeScript marks it on purpose: Type 'string' is not assignable to type 'number', meaning text where a number has to go.

Sending is typed. Listening is harder, because the listener only has the name, and "cart:add" isn't in TypeScript's list:

1const cartBadge = document.createElement("span");2 3cartBadge.addEventListener("cart:add", (event) => {4  console.log(`Added ${event.detail.quantity} ${event.detail.name}`);5});6 7cartBadge.dispatchEvent(new CustomEvent("cart:add", { detail: { name: "Tea", quantity: 2 } }));

Line 3 listens for "cart:add" on a cart badge, and line 7 sends one. The listener's event is a plain Event, so both reads on line 4 get Property 'detail' does not exist on type 'Event', on purpose. The code still prints Added 2 Tea. Checking event instanceof CustomEvent doesn't help much: it gives CustomEvent<any>, because instanceof can't look inside detail.

The fix is to add the name to the list. Interfaces with the same name join together, so you can add a line to HTMLElementEventMap (the Declaration merging lesson does this for window):

1type CartAdd = { name: string; quantity: number };2 3declare global {4  interface HTMLElementEventMap {5    "cart:add": CustomEvent<CartAdd>;6  }7}8 9const cartBadge = document.createElement("span");10 11cartBadge.addEventListener("cart:add", (event) => {12  //                                    ^?13  console.log(`Added ${event.detail.quantity} ${event.detail.name}`);14});15 16cartBadge.dispatchEvent(new CustomEvent<CartAdd>("cart:add", { detail: { name: "Tea", quantity: 2 } }));

Lines 3 to 7 add "cart:add" with the type CustomEvent<CartAdd>. declare global means "add this to the types every file sees". Now the answer on line 12 shows the listener's event is a CustomEvent<CartAdd>, line 13 has no errors, and the code prints Added 2 Tea.

declare global only works in a module: a file with an import or an export. This page treats every example as a module. In your own project, a file with neither gets the error Augmentations for the global scope can only be directly nested in external modules, so add export {}; at the end of it (Globals & module augmentation explains why).

The list types the listeners. It doesn't check the senders, because dispatchEvent accepts any event:

1type CartAdd = { name: string; quantity: number };2 3declare global {4  interface HTMLElementEventMap {5    "cart:add": CustomEvent<CartAdd>;6  }7}8 9const cartBadge = document.createElement("span");10cartBadge.addEventListener("cart:add", (event) => {11  console.log(`Added ${event.detail.quantity} ${event.detail.name}`);12});13 14cartBadge.dispatchEvent(new CustomEvent("cart:add", { detail: { title: "Tea" } }));

Line 14 sends a detail with a title and no name or quantity. TypeScript reports nothing, and the code prints Added undefined undefined. To check both sides, send and listen through two small functions:

1type CartAdd = { name: string; quantity: number };2 3function sendCartAdd(target: EventTarget, detail: CartAdd) {4  target.dispatchEvent(new CustomEvent<CartAdd>("cart:add", { detail }));5}6 7function onCartAdd(target: EventTarget, handler: (detail: CartAdd) => void) {8  target.addEventListener("cart:add", (event) => {9    handler((event as CustomEvent<CartAdd>).detail);10  });11}12 13const cart = new EventTarget();14onCartAdd(cart, (item) => console.log(`Added ${item.quantity} ${item.name}`));15sendCartAdd(cart, { name: "Cake", quantity: 1 });

Lines 3 to 5 make sendCartAdd, which only accepts a CartAdd. Lines 7 to 11 make onCartAdd, which hands its handler a CartAdd. Line 9 is the one place that says "this event is a CustomEvent<CartAdd>" with as. That promise holds as long as every "cart:add" event is sent through sendCartAdd. Line 13 makes a plain EventTarget to send them on, and the code prints Added 1 Cake.

The table below compares the three ways. Read each row as: this way, what it types, and what can still go wrong.

A search form with keyboard shortcuts

A real search form sends its text when you press Enter or the button, and clears when you press Escape. Its handlers are named functions, so each one says which event it takes:

1const form = document.createElement("form");2const searchBox = document.createElement("input");3form.append(searchBox);4document.body.append(form);5 6function handleKey(event: KeyboardEvent) {7  if (event.key === "Escape") {8    searchBox.value = "";9    console.log("Search cleared");10  }11}12 13function handleSubmit(event: SubmitEvent) {14  event.preventDefault();15  console.log(`Searching for ${searchBox.value}`);16}17 18searchBox.addEventListener("keydown", handleKey);19form.addEventListener("submit", handleSubmit);20 21searchBox.value = "green tea";22form.requestSubmit();23searchBox.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));

Lines 1 to 4 build a form holding a search box and put it on the page. Lines 6 to 11 handle key presses: line 6 says the handler takes a KeyboardEvent, so line 7 can compare event.key with "Escape". Lines 13 to 16 handle sending the form: a SubmitEvent, and line 14's preventDefault() stops the page from reloading (Form events covers that). Lines 18 and 19 attach both, and TypeScript checks each handler against its event's name. Line 22 sends the form and line 23 presses Escape, so the code prints Searching for green tea, then Search cleared.

The handlers read searchBox directly, not event.target, so they need no checks. Now sort some one-line listeners by what TypeScript says about them:

Common mix-ups

An event name works only when TypeScript can see the exact name. Kept in a let variable, it can't:

1const searchBox = document.createElement("input");2let eventName = "keydown";3//  ^?4 5searchBox.addEventListener(eventName, (event) => {6  console.log(`You pressed ${event.key}`);7});

Line 2 stores the name with let, so it could change later, and the answer on line 3 shows its type is string: any text (the Literal types lesson explains why). Any text can't be looked up, so line 5's listener gets a plain Event, and line 6 is marked on purpose. With const, as in the playground, the type is exactly "keydown".

And a custom event's type doesn't make its detail appear:

1type CartAdd = { name: string; quantity: number };2 3const added = new CustomEvent<CartAdd>("cart:add");4console.log(added.detail);5console.log(added.detail.name);

Line 3 makes a CustomEvent<CartAdd> with no options. TypeScript has no error: the detail option is optional. When it runs, the browser sets detail to null, so line 4 prints null and line 5 throws a TypeError.

• "A misspelled event name is an error." No. Any text is allowed as a name. The listener gets a plain Event, and an error appears only if you read something a plain Event lacks.
• "event.currentTarget has the type of the element I listen on." No. It's EventTarget | null for every event. Use the variable you attached the listener to.
• "event.target as HTMLInputElement checks the target." No. It's a promise you make, and nothing checks it. instanceof checks it while the page runs.
• "TypeScript types an input listener's event as an InputEvent." No. It lists "input" as a plain Event, because a <select> or a checkbox sends a plain Event with that name. "beforeinput" is the one TypeScript types as an InputEvent.
• "A handler must take exactly the event's type." No. It may ask for less, like Event, but never for more, like a MouseEvent for a key press.
• "Adding my event to the list checks dispatchEvent." No. The list types listeners. Senders are checked only if they go through a typed function like sendCartAdd.
• "CustomEvent<CartAdd> always has a detail." No. Leave the option out, and detail is null, with no error.

Practice exercises

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

1const form = document.createElement("form");2 3form.addEventListener("submit", (event) => {4  event.preventDefault();5});

1const form = document.createElement("form");2 3form.addEventListener("submit", (event) => {4  //                               ^?5  event.preventDefault();6});

const addButton = document.createElement("button");
const searchBox = document.createElement("input");

addButton.addEventListener("click", (event) => {
  console.log(event.clientX);
});

searchBox.addEventListener("keydown", (event) => {
  console.log(event.clientX);
});

1const addButton = document.createElement("button");2const searchBox = document.createElement("input");3 4addButton.addEventListener("click", (event) => {5  console.log(event.clientX);6});7 8searchBox.addEventListener("keydown", (event) => {9  console.log(event.key); // line 9: a key press has no clientX10});

1function showPosition(event) {2  console.log(`Clicked at ${event.clientX}`);3}4 5const map = document.createElement("div");6map.addEventListener("click", showPosition);7map.dispatchEvent(new MouseEvent("click", { clientX: 40 }));

1function showPosition(event: MouseEvent) {2  console.log(`Clicked at ${event.clientX}`);3}4 5const map = document.createElement("div");6map.addEventListener("click", showPosition);7map.dispatchEvent(new MouseEvent("click", { clientX: 40 }));

1const searchBox = document.createElement("input");2 3searchBox.addEventListener("input", (event) => {4  console.log(`Searching for ${event.target.value}`);5});6 7searchBox.value = "cake";8searchBox.dispatchEvent(new Event("input"));

1const searchBox = document.createElement("input");2 3searchBox.addEventListener("input", (event) => {4  if (event.target instanceof HTMLInputElement) {5    console.log(`Searching for ${event.target.value}`);6  }7});8 9searchBox.value = "cake";10searchBox.dispatchEvent(new Event("input"));

1type Filter = { category: string };2 3const menu = document.createElement("div");4 5menu.addEventListener("filter:change", (event) => {6  console.log(`Showing ${event.detail.category}`);7});8 9menu.dispatchEvent(new CustomEvent<Filter>("filter:change", { detail: { category: "cake" } }));

1type Filter = { category: string };2 3declare global {4  interface HTMLElementEventMap {5    "filter:change": CustomEvent<Filter>;6  }7}8 9const menu = document.createElement("div");10 11menu.addEventListener("filter:change", (event) => {12  console.log(`Showing ${event.detail.category}`);13});14 15menu.dispatchEvent(new CustomEvent<Filter>("filter:change", { detail: { category: "cake" } }));

1const menu = document.createElement("ul");2menu.innerHTML = `<li><button data-product="Tea"><span>Add tea</span></button></li>3<li><button data-product="Cake"><span>Add cake</span></button></li>`;4 5menu.addEventListener("click", (event) => {6  const button = event.target.closest("button");7  console.log(`Added ${button.dataset.product}`);8});9 10menu.querySelectorAll("span")[1].click();

1const menu = document.createElement("ul");2menu.innerHTML = `<li><button data-product="Tea"><span>Add tea</span></button></li>3<li><button data-product="Cake"><span>Add cake</span></button></li>`;4 5menu.addEventListener("click", (event) => {6  if (!(event.target instanceof Element)) return;7  const button = event.target.closest("button");8  if (button) console.log(`Added ${button.dataset.product}`);9});10 11menu.querySelectorAll("span")[1].click();

Check your understanding

For each question, start from the event's name and look up its type. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• The name you pass to addEventListener picks the event's type: "keydown" gives a KeyboardEvent, "click" a PointerEvent.
• TypeScript looks the name up in lists like HTMLElementEventMap. A name it doesn't know gives a plain Event, with no error on the name.
• event.target and event.currentTarget are both EventTarget | null. Use your element variable, or check with instanceof.
• A handler written on its own needs its event type written out. It may ask for less than the event gives, never more.
• CustomEvent<T> types the detail you send. For listeners, add the name to the event list or use typed helpers.

Coming next: Typing fetch & JSON. Events come with types from the browser, but data from a server has none until you check it.