stopPropagation и когда он вреден

Здесь будет встроен видео-разбор темы (5–7 минут, YouTube / RuTube / VK Видео) — тем, кто лучше воспринимает на слух, текст ниже не обязателен.

Вызов event.stopPropagation() обрывает путешествие события по цепочке предков. Обработчики выше по дереву — на <div>, на body, на document — просто не будут вызваны. Само событие при этом никуда не исчезает: оно уже сработало там, где его поймали, и действие браузера по умолчанию тоже остаётся в силе.

js

const box = document.querySelector("#box");
const log = [];

box.addEventListener("click", (event) => log.push("box <- " + event.target.id));

document.querySelector("#quiet").addEventListener("click", (event) => {
  event.stopPropagation();
});

document.querySelector("#loud").click();
document.querySelector("#quiet").click();

console.log(log);

страница примера

Сначала предположите, что выведет код

Важная деталь, о которой забывают: остановка касается только пути вверх. Обработчики, висящие на том же самом элементе, отработают все до единого — в порядке подписки. stopPropagation() не выключает соседей, он закрывает дверь наружу.

js

const btn = document.querySelector("#btn");
const log = [];

btn.addEventListener("click", (event) => {
  event.stopPropagation();
  log.push("первый");
});
btn.addEventListener("click", () => log.push("второй"));

btn.click();
console.log(log.join(", "));

страница примера

Сначала предположите, что выведет код

Если нужно заткнуть и соседей, есть более тяжёлый инструмент — event.stopImmediatePropagation(). Он делает всё то же, что stopPropagation(), и вдобавок отменяет остальные обработчики этого же события на этом же элементе — те, что подписались после текущего.

js

const box = document.querySelector("#box");
const btn = document.querySelector("#btn");
const log = [];

box.addEventListener("click", () => log.push("box"));

btn.addEventListener("click", (event) => {
  event.stopImmediatePropagation();
  log.push("первый");
});
btn.addEventListener("click", () => log.push("второй"));

btn.click();
console.log(log);

страница примера

Сначала предположите, что выведет код

Обратите внимание, насколько результат зависит от порядка подписки: подключись «второй» раньше — и он бы успел отработать. Поведение кода начинает зависеть от того, в каком порядке загрузились скрипты. Это плохой фундамент, и потому stopImmediatePropagation() — почти всегда признак того, что архитектура где-то не сложилась.

Вызов	Что делает	Чего НЕ делает
preventDefault()	Отменяет действие браузера по умолчанию: переход по ссылке, отправку формы, прокрутку	Не мешает событию всплывать — все обработчики выше отработают
stopPropagation()	Не пускает событие дальше по цепочке предков	Не отменяет действие браузера и не трогает другие обработчики того же элемента
stopImmediatePropagation()	То же плюс отменяет оставшиеся обработчики на этом элементе	Не отменяет действие браузера
return false в HTML-атрибуте onclick	Работает как preventDefault()	Ничего не останавливает во всплытии; внутри addEventListener не значит вообще ничего

Всплытие — не деталь реализации, а публичный интерфейс страницы. На нём держится делегирование: один обработчик на списке обслуживает все элементы, включая те, которых ещё нет в DOM. Одна остановка внутри — и делегирование про эту кнопку не узнает никогда.

js

const menu = document.querySelector("#menu");
const clicked = [];

// делегирование: один обработчик на весь список
menu.addEventListener("click", (event) => {
  const button = event.target.closest("button");
  if (button) clicked.push(button.id);
});

// сторонний виджет «прибрался» на своей кнопке
document.querySelector("#b").addEventListener("click", (event) => {
  event.stopPropagation();
});

document.querySelector("#a").click();
document.querySelector("#b").click();

console.log(clicked);

страница примера

Сначала предположите, что выведет код

На document обычно висит целая толпа слушателей, которых вы не писали: счётчик аналитики, закрытие выпадающего меню по клику снаружи, подсветка активной вкладки, хоткеи. Все они молча перестают работать в том углу страницы, где кто-то однажды поставил stopPropagation().

js

const stats = [];
document.addEventListener("click", (event) => stats.push(event.target.id));

document.querySelector("#close").addEventListener("click", (event) => {
  event.stopPropagation();
});

document.querySelector("#close").click();
console.log(stats.length);

страница примера

Сначала предположите, что выведет код

Худшее в таком баге — расстояние между причиной и симптомом. Жалоба звучит как «аналитика не считает клики в модалке» или «меню не закрывается только на странице заказа», а виновная строка лежит в другом файле, написана полгода назад и выглядит совершенно безобидно. С React то же самое: он слушает клики на корне приложения, и остановка между кнопкой и корнем молча оставит без события все его обработчики — это разбирает статья «Всплытие, отмена и остановка в React».

Первый вопрос: а точно ли вы хотели остановить событие? Чаще всего хотели отменить действие браузера — переход по ссылке или отправку формы. Это preventDefault(), и он не мешает событию идти дальше.

js

const form = document.querySelector("#form");
const log = [];

document.addEventListener("submit", () => log.push("документ тоже увидел"));

form.addEventListener("submit", (event) => {
  event.preventDefault();
  log.push("форма перехвачена");
});

form.requestSubmit();
console.log(log);

страница примера

Сначала предположите, что выведет код

Второй приём — исправлять там, где мешает. Классика: «клик вне меню закрывает меню», и чтобы кнопка-переключатель не закрывала его сама, на неё вешают stopPropagation(). Но условие «этот клик — внутри меню» принадлежит обработчику на document, а не кнопке. Проверка через contains() или closest() решает задачу, никого не ограбив.

js

const menu = document.querySelector("#menu");
let open = true;

document.addEventListener("click", (event) => {
  if (menu.contains(event.target)) return; // клик внутри меню его не закрывает
  open = false;
});

document.querySelector("#toggle").click();
console.log(open);

document.querySelector("#outside").click();
console.log(open);

страница примера

Сначала предположите, что выведет код

Когда внешний и внутренний обработчики — оба ваши, договоритесь через флаг на объекте события. Событие продолжает всплывать, аналитика и делегирование его видят, а ваш внешний обработчик знает, что клик уже обработан.

js

const card = document.querySelector("#card");
const fav = document.querySelector("#fav");
const log = [];

fav.addEventListener("click", (event) => {
  event.handledByCard = true; // помечаем, а не глушим
  log.push("в избранное");
});

card.addEventListener("click", (event) => {
  if (event.handledByCard) return;
  log.push("открыть карточку");
});

fav.click();
card.click();
console.log(log);

страница примера

Сначала предположите, что выведет код

Запрета нет — есть цена. Остановка честна там, где вы владеете всем маршрутом: собственное событие (new CustomEvent("widget:pick")), которое вы сами породили и сами слушаете, изолированный компонент внутри Shadow DOM, отладочная заглушка на пять минут. Общее правило: глушить можно то, что придумали вы, и в пределах того дерева, за которое отвечаете вы.

Всё остальное — click, keydown, focusin, submit на публичной странице — общий ресурс. Библиотека, аналитика, ассистивные технологии и ваш собственный код из соседней команды рассчитывают, что события доходят до document.

Перед каждым stopPropagation спросите себя: что именно я хочу отменить? Если действие браузера — нужен preventDefault. Если чужую реакцию — договоритесь с этим кодом, а не глушите событие для всей страницы.

Найти источник проще всего, временно подменив сам метод: любой вызов оставит след. В настоящей отладке вместо массива пишут console.trace() — он покажет стек и файл, где стоит остановка.

js

const original = Event.prototype.stopPropagation;
const calls = [];

Event.prototype.stopPropagation = function () {
  calls.push(this.type); // в реальной отладке здесь console.trace()
  return original.call(this);
};

document.querySelector("#btn").addEventListener("click", (event) => {
  event.stopPropagation();
});
document.querySelector("#btn").click();

Event.prototype.stopPropagation = original; // вернули как было
console.log(calls);

страница примера

Сначала предположите, что выведет код

А если исправить чужой виджет нельзя, есть надёжный обход: слушайте в фазе захвата. Захват идёт сверху вниз, от document к цели, и до элемента-виновника ваш обработчик уже отработал. Именно так защищаются серьёзные счётчики аналитики.

js

const log = [];
document.addEventListener("click", () => log.push("capture"), true);
document.addEventListener("click", () => log.push("bubble"));

document.querySelector("#btn").addEventListener("click", (event) => {
  event.stopPropagation();
});

document.querySelector("#btn").click();
console.log(log);

страница примера

Сначала предположите, что выведет код

stopPropagation() обрывает путь события к предкам, но не мешает другим обработчикам того же элемента — их отменяет только stopImmediatePropagation().
Событие, остановленное на кнопке, не увидят ни делегирование выше, ни аналитика на document, ни «закрытие по клику снаружи» — а баг всплывёт далеко от причины.
Отмена действия браузера — это preventDefault(); путать её с остановкой всплытия дорого.
Вместо остановки решайте вопрос там, где он мешает: contains()/closest() во внешнем обработчике или флаг на объекте события.
Обработчик в фазе захвата на document увидит событие даже тогда, когда цель его глушит — так спасают аналитику в чужом коде.

1/3На кнопку повесили два обработчика click. Первый вызывает event.stopPropagation(). Что будет со вторым?

2/3Аналитика слушает click на document в обычной фазе всплытия. Виджет вызывает stopPropagation на своей кнопке. Что увидит аналитика?

3/3Внутри карточки есть ссылка. Нужно, чтобы браузер по ней не переходил, но клик по-прежнему считался аналитикой на document.

Уберите остановку, сохранив поведение

Клик по карточке открывает её, клик по кнопке «В избранное» — только добавляет в избранное. Автор решил задачу через stopPropagation(), и теперь аналитика на document не видит этот клик. Перепишите обработчики так, чтобы карточка не открывалась, а аналитика сработала.

js

const log = [];
document.addEventListener("click", () => log.push("аналитика"));

const card = document.querySelector("#card");
const fav = document.querySelector("#fav");

fav.addEventListener("click", (event) => {
  event.stopPropagation(); // <- переписать это место
  log.push("в избранное");
});
card.addEventListener("click", () => log.push("открыть карточку"));

fav.click();
console.log(log); // сейчас ["в избранное"], нужно ["в избранное", "аналитика"]

страница примера

Сначала предположите, что выведет код

Условие «клик пришёл из кнопки» принадлежит обработчику карточки — там его и проверяем. Подойдёт и флаг на событии, и closest().

jsлистинг · не запускается

fav.addEventListener("click", (event) => {
  event.handledByFav = true;
  log.push("в избранное");
});

card.addEventListener("click", (event) => {
  if (event.handledByFav) return;
  log.push("открыть карточку");
});

fav.click();
console.log(log); // ["в избранное", "аналитика"]

fav.addEventListener("click", (event) => {
  event.handledByFav = true;
  log.push("в избранное");
});

card.addEventListener("click", (event) => {
  if (event.handledByFav) return;
  log.push("открыть карточку");
});

fav.click();
console.log(log); // ["в избранное", "аналитика"]

Вариант без флага — проверка цели: if (event.target.closest("#fav")) return; в обработчике карточки. Оба решения оставляют событие живым, и всё, что висит выше, продолжает работать.

Услышьте клик, который глушат

Виджет чужой, править его нельзя: он вызывает stopPropagation(). Ваша задача — досчитать клик, изменив только свою строку подписки.

js

const hits = [];

// чужой виджет, менять нельзя:
document.querySelector("#btn").addEventListener("click", (event) => {
  event.stopPropagation();
});

// ваш код: почините счётчик
document.addEventListener("click", () => hits.push(1));

document.querySelector("#btn").click();
console.log(hits.length); // сейчас 0, нужно 1

страница примера

Сначала предположите, что выведет код

Подпишитесь в фазе захвата — третьим аргументом true или объектом { capture: true }.

jsлистинг · не запускается

document.addEventListener("click", () => hits.push(1), true);

document.querySelector("#btn").click();
console.log(hits.length); // 1

document.addEventListener("click", () => hits.push(1), true);

document.querySelector("#btn").click();
console.log(hits.length); // 1

Захват идёт сверху вниз, от document к цели, поэтому ваш обработчик отрабатывает до кнопки. Остановка на цели наступает уже после и на него не влияет.

stopPropagation и когда он вреден

Видеоразбор темы за 5–7 минут

Что именно останавливает stopPropagationСобытие перестаёт подниматься к предкам

stopImmediatePropagationГлушит и соседей на том же элементе

Почему это ломает чужой кодДелегирование, аналитика и закрытие попапов

Чем заменить в большинстве случаевpreventDefault, contains и флаг события

Когда остановка оправданаСвоё событие в своём поддереве

Если глушит чужой кодНайти виновника и услышать событие

Итогошпаргалка по теме

Проверьте себятри быстрых вопроса

Задачидве задачи с решениями

Уберите остановку, сохранив поведение

Услышьте клик, который глушат