Event delegation in JavaScript

One listener for many elements

An event listener is a function that runs when something happens to an element, such as a click. Event delegation means you put one listener on a parent element, instead of one listener on every child. When a child is clicked, the listener on the parent runs. It checks which child was clicked, and then it decides what to do.

This works because of bubbling, which you met in the lesson Bubbling & capturing. A click starts on the element you clicked. Then it travels up to that element's parent, then to the parent's parent, and so on. So a listener on a parent hears clicks on everything inside it.

In this lesson, one listener on a to-do list handles every button in the list. It even handles buttons that are added later. You will see this pattern in menus, tables, inboxes, and any page made of many repeated parts.

The hard part is not adding the one listener. The hard part is the filter: the code that decides which clicks matter. The parent hears every click inside it, even clicks on empty space. So good delegated code checks each click and ignores the ones it does not need.

Here is the pattern in a to-do list. Each row has two buttons:

• Toggle marks the row as done, or not done.
• Delete removes the row.

Without delegation, you add one click listener to every button. Three rows with two buttons each need six listeners. A fourth row needs two more.

With delegation, you add one listener to the ul, the list element. Say you click the small icon inside a button. The click bubbles up to the list. Then the listener does three things:

1. It looks at the element where the click started.
2. It finds the nearest element that has a data-action attribute.
3. It runs the job that the attribute names.

1const list = document.querySelector("#todos");2 3list.addEventListener("click", (event) => {4  if (!(event.target instanceof Element)) return;5 6  const button = event.target.closest("[data-action]");7  if (!button || !list.contains(button)) return;8 9  const item = button.closest("[data-id]");10  const action = button.dataset.action;11 12  if (action === "toggle") item.classList.toggle("done");13  if (action === "delete") item.remove();14});

Click Add a later item in the playground. The new row's buttons work right away. This is because the listener is on the list, not on the buttons. The new row is inside the list, so its clicks bubble up to the list, just like the first rows. This is the biggest everyday reason to use delegation.

The first problem appears when a button has other elements inside it. A user might click the icon <span> inside the button, not the button itself. Then event.target, the element where the click started, is the span.

Say your code asks event.target.matches("button"). The method matches() checks if one element fits a CSS selector. Here the answer is false, because the target is the span, not the button.

closest(selector) solves this. It checks the element itself first. If that does not match, it checks the parent, then the parent's parent, and so on. It stops at the first match. If it reaches the top of the page without a match, it returns null.

closest() can climb above your list. So check the result with list.contains(button). The method contains() returns true when the button is inside the list.

1list.addEventListener("click", (event) => {2  if (!(event.target instanceof Element)) return;3 4  const wrong = event.target.matches("button");5  const button = event.target.closest("button");6 7  if (!button || !list.contains(button)) return;8  console.log(button.dataset.action);9});

const clicked = "span.icon";
const command = clicked.startsWith("span") ? "delete" : "ignored";
console.log(command);

This small model starts with a click on an icon. Then it picks the job of the button around the icon. It prints delete, even though the icon itself is not a button.

How to read this table: each row is one tool. The columns say what the tool gives you and how a delegated listener uses it.

Check the target before you call closest(). In browser code, event.target is not always an Element. An Element is a tag on the page, such as a button or a span. Only elements have closest(). The usual check is if (!(event.target instanceof Element)) return;.

• instanceof Element asks: "is this value an element?"
• return stops the listener early when the answer is no.

The parent listener needs to know which job each button does. A data-* attribute is a good place to write that down. It is an attribute you make up yourself, and its name starts with data-. The browser does nothing with it, so it is free for your code to use.

For example, data-action="delete" on a button means: "when this is clicked, delete something." In JavaScript, you read it with button.dataset.action.

The playground below puts one listener on the demo panel, not on document (the whole page). So the listener only hears clicks inside the panel. A demo should not react to clicks on the rest of the page.

1panel.addEventListener("click", (event) => {2  if (!(event.target instanceof Element)) return;3 4  const toggle = event.target.closest("[data-toggle]");5  if (toggle && panel.contains(toggle)) {6    document.querySelector(toggle.dataset.toggle).hidden = false;7  }8 9  const copy = event.target.closest("[data-copy]");10  if (copy && panel.contains(copy)) {11    output.textContent = copy.dataset.copy;12  }13});

Each job in the code follows the same three steps:

1. Find the nearest element with that data attribute.
2. Check that the element is inside the panel.
3. Read its data value, and do the job.

You can add more jobs this way. Keep each job small and easy to read. If a job needs a lot of its own data, give that element its own listener instead.

Elements added later

Delegation is most useful when children are created after the listener is added. For example:

• search results
• chat messages
• notifications
• table rows loaded from a server

The parent is already on the page. The children arrive later.

// One listener per button: only buttons on the page right now get one.
document.querySelectorAll("button[data-action]").forEach((button) => {
  button.addEventListener("click", handleButton);
});

// One listener on the list: buttons added later bubble here too.
list.addEventListener("click", handleListClick);

The first version loops over the buttons that exist now. A button added later gets no listener. The second version adds one listener to the list, so buttons added later are handled too.

const handled = ["todo-1"];
const laterItem = "todo-2";
handled.push(laterItem);
console.log(handled.join(","));

It prints todo-1,todo-2. The second id is added to the data, but no new listener is added. The one parent listener still handles both.

Delegation only works when three things are true:

• The new element is inside the parent.
• The event bubbles.
• No child stops the event before it reaches the parent.

The next sections show what to do when one of these is not true.

Now step through the listener one line at a time. First choose where the click lands:

• on the icon inside the Delete button,
• on the text of the Toggle button,
• on empty space in the list,
• on empty space in a list that sits inside an outer row.

The replay is a model written for this lesson. The live playgrounds above run the same checks in your browser.

1const list = document.querySelector("#todos");2 3list.addEventListener("click", (event) => {Run4  if (!(event.target instanceof Element)) return;5 6  const button = event.target.closest("[data-action]");7  if (!button || !list.contains(button)) return;8 9  const item = button.closest("[data-id]");10  const action = button.dataset.action;11  route(action, item?.dataset.id);12});

Look at the empty-space case. The parent hears clicks it does not need. Stopping early with return is not a bug. It is the filter doing its job.

The outer-row case shows why contains() matters. A selector only says what an element looks like. It does not say which list the element belongs to.

Delegation is a tool, not a rule. It is a great fit when many children do the same kind of job, and when children are added later. It is a poor fit in three cases:

• The event does not bubble.
• A child calls stopPropagation(), which stops the event from moving up.
• There is only one button, so a listener right on it is simpler.

Which events bubble? click, input, and change bubble, so they are often delegated. focus, blur, mouseenter, mouseleave, and the load event of an element do not bubble. For those, you have three choices:

• Use a similar event that does bubble: focusin, focusout, mouseover, or pointerover.
• Put the listener right on the element.
• Use a capture listener on the parent. It runs while the event travels down, before it reaches the element.

const events = ["click", "input", "change"];
const delegated = events.includes("click");
console.log(delegated);

It prints true, because click is in the list of bubbling events this listener handles. Events that do not bubble need another plan.

const eventName = "focusin";
const bubbles = eventName === "focusin";
console.log(bubbles);

It prints true. focusin bubbles, so a parent can hear it and then find the field that got focus.

Where you will use this

Delegation appears in everyday code wherever the same markup repeats. Follow these steps for a list, a menu, or a table:

1. Pick the smallest parent that holds all the repeated buttons and stays on the page.
2. Listen on that parent for an event that bubbles.
3. Check that event.target is an Element.
4. Use closest() to find the button that was clicked.
5. Check parent.contains(button).
6. Read its dataset values, and call a small function for the job.

const actions = {
  save(item) {
    console.log("save", item.dataset.id);
  },
  delete(item) {
    item.remove();
  },
};

list.addEventListener("click", (event) => {
  if (!(event.target instanceof Element)) return;
  const button = event.target.closest("[data-action]");
  if (!button || !list.contains(button)) return;

  const item = button.closest("[data-id]");
  const action = button.dataset.action;
  actions[action]?.(item);
});

The actions object links each job name to a function. The listener finds the button and its row. Then it calls actions[action]?.(item). The ?. skips the call when no job has that name.

Three places this pattern appears

A to-do list sends a job to the row that holds the clicked button. This small model deletes the matching row and prints the row that is left.

const todos = [
  { id: "todo-1", done: false },
  { id: "todo-2", done: false },
];
const clickedButton = { dataset: { action: "delete", id: "todo-1" } };
const index = todos.findIndex((todo) => todo.id === clickedButton.dataset.id);
if (clickedButton.dataset.action === "delete") todos.splice(index, 1);
console.log(todos.map((todo) => todo.id).join(","));

It prints todo-2. Deleting todo-1 leaves only todo-2.

A table uses the same steps for the buttons in each row. This model reads the row id, then looks up the current status of that row.

const rows = new Map([
  ["order-7", "Ready"],
  ["order-8", "Packed"],
]);
const clickedButton = { dataset: { action: "ship", rowId: "order-7" } };
console.log(clickedButton.dataset.action + ":" + rows.get(clickedButton.dataset.rowId));

It prints ship:Ready: the job name and the row's status together.

Menus often use one parent listener too. Here the job changes a small value instead of removing a row.

const menu = { open: false };
const clickedButton = { dataset: { action: "open-menu" } };
if (clickedButton.dataset.action === "open-menu") menu.open = true;
console.log(menu.open);

It prints true, because the open-menu job set menu.open to true.

const matches = ["outer-list", "inner-list"];
const owner = "inner-list";
console.log(matches.includes(owner));

It prints true, because "inner-list", the list being checked, is in the matches array. A real listener does this check with container.contains(match).

In React, Vue, Svelte, and similar tools, you often use the tool's own event system instead of this exact code. The idea still helps: repeated children send an action up, and one parent decides what to do.

Common mistakes

• "Delegation means a listener on document." Usually not. Put the listener on the smallest parent that holds the buttons. Then clicks on other parts of the page do not run it.
• "closest() always stays inside my list." It can climb to elements above the list. Check container.contains(match).
• "Every event can be delegated." Delegation needs bubbling. Some events need a similar event that bubbles, a capture listener, or a listener right on the element.
• "One listener is always faster." Not always. The parent listener runs for every click inside the parent, even the clicks it ignores.
• "stopPropagation() is harmless." It can be useful. But it stops the event before it reaches the parent listener.

How to read this table: each row is a question. The columns answer it for one listener on the parent, and for a listener on each element.

const parentSawClick = true;
const childStopped = true;
console.log(parentSawClick && !childStopped);

It prints false. When a child stops the event, the parent's delegated listener never sees that click.

Key takeaways

• Event delegation puts one listener on a parent. That listener handles events that bubble up from the children.
• Use event.target to start, closest() to find the button, and contains() to check that the button is inside the parent.
• A data-action attribute names the job of each button, so one listener can handle many jobs.
• Elements added later work too, as long as they are inside the parent.
• Delegation needs bubbling. Use another plan for events that do not bubble, or when a child stops the event.

Final definition: Event delegation means handling the events of many child elements, now and in the future, with one listener on a parent. The listener checks where each event started, and then it picks the right job.

Up next: Default actions.