블로그 목록

자바스크립트 동적 추가 요소 이벤트 미작동 원인과 이벤트 위임 패턴 해결 방법

자바스크립트로 동적 생성한 버튼이나 목록에 클릭 이벤트가 반응하지 않는 문제의 원인을 살펴보고, 이벤트 위임 기법과 closest 메서드를 활용한 실무 해결 절차를 알아봅니다.

개발 자바스크립트 동적 생성 요소 이벤트 미동작 해결 방법
자바스크립트 동적 DOM 요소에 이벤트 위임 기법을 적용하는 코드 다이어그램

동적 생성 요소의 이벤트 미동작 증상과 재현 조건

웹 애플리케이션 개발 중 API 응답 데이터를 기반으로 목록을 렌더링하거나, 사용자가 '추가' 버튼을 눌러 화면에 새로운 요소를 삽입할 때 클릭 이벤트가 전혀 실행되지 않는 현상이 자주 발생합니다. 기존 마크업에 존재하던 기본 버튼은 정상적으로 클릭 핸들러가 동작하지만, document.createElement나 innerHTML 등으로 나중에 추가된 버튼을 클릭하면 콘솔 창에 아무런 로그도 찍히지 않는 상태가 대표적인 증상입니다.

이러한 현상은 주로 페이지 초기화 시점에 document.querySelectorAll('.delete-btn')과 같이 요소 목록을 가져와 forEach 반복문으로 addEventListener를 직접 바인딩했을 때 재현됩니다. 스크립트가 실행되는 순간에는 브라우저 메모리에 해당 동적 요소가 존재하지 않으므로 이벤트 리스너가 연결되지 않으며, 화면상에 시각적으로 버튼이 노출되더라도 내부적으로는 바인딩된 핸들러가 없는 무반응 상태로 남게 됩니다.

javascript-dynamic-element-event-unresponsive-symptom

이벤트 리스너 미동작의 핵심 원인 분석

이 문제의 가장 근본적인 원인은 '이벤트 리스너 등록 시점'과 'DOM 노드 생성 시점'의 불일치입니다. 브라우저는 HTML 문서를 파싱하고 스크립트를 실행할 때, 그 순간 DOM 트리에 실제로 존재하는 노드에만 참조를 걸고 이벤트 핸들러를 등록합니다. 이후 비동기 통신이나 사용자 조작으로 새로운 노드가 DOM 트리에 진입하더라도, 브라우저가 과거에 실행되었던 이벤트 바인딩 코드를 다시 실행해주지는 않습니다.

두 번째 원인은 querySelectorAll이 반환하는 정적 노드리스트(Static NodeList)의 특성에 있습니다. 이 메서드로 수집한 요소 컬렉션은 DOM에 변화가 생겨도 자동으로 최신 상태를 반영하지 않는 스냅샷 역할을 합니다. 결과적으로 초기 실행 시점에 수집된 목록에만 핸들러가 등록되어, 런타임에 새로 추가된 요소들은 리스너 바인딩 대상에서 완전히 누락되는 구조적 한계가 발생합니다.

javascript-dom-lifecycle-and-listener-binding-timing

브라우저 개발자 도구를 활용한 이벤트 바인딩 확인 순서

문제 해결에 앞서 실제로 이벤트가 바인딩되지 않은 것인지, 아니면 핸들러 내부 로직 오류인지를 단계별로 검증해야 합니다. 우선 크롬 등 브라우저의 개발자 도구(F12)를 열고 'Elements' 탭으로 이동합니다. 반응하지 않는 동적 요소를 인스펙터로 선택한 뒤 우측 보조 패널의 'Event Listeners' 탭을 확인합니다. 여기에 click 이벤트 항목이 없거나 상위 조상 노드로부터 상속되는 리스너가 표시되지 않는다면 바인딩 누락이 확실합니다.

다음으로 콘솔 창에서 대상 요소를 직접 선택해 addEventListener를 임시 실행해보거나, 렌더링 함수 직후에 console.log를 배치하여 요소가 생성된 직후의 참조 상태를 추적합니다. 만약 렌더링 로직 안에서 매번 리스너를 직접 바인딩하고 있는데도 동작하지 않는다면, 렌더링 함수 호출 이전에 스크립트 실행이 중단되는 문법 오류나 비동기 순서 꼬임이 있는지 콘솔 에러 로그를 점검해야 합니다.

chrome-devtools-event-listeners-tab-inspection

이벤트 위임 패턴과 closest 메서드를 활용한 해결 예시

가장 권장되는 표준 해결책은 브라우저의 이벤트 버블링 메커니즘을 활용한 '이벤트 위임(Event Delegation)' 패턴을 적용하는 것입니다. 동적으로 추가될 요소 하나하나에 리스너를 붙이지 않고, 이 요소들을 감싸고 있는 상위 컨테이너(예: ul, div.list-container)에 단 하나의 이벤트 리스너를 등록합니다. 하위 요소에서 클릭이 발생하면 이벤트가 부모 요소로 전파되므로, 상위 요소의 핸들러에서 이를 감지할 수 있습니다.

구현 시에는 이벤트 객체의 e.target을 직접 비교하기보다 Element.prototype.closest() 메서드를 사용하는 것이 안전합니다. 예를 들어 listContainer.addEventListener('click', (e) => { const deleteBtn = e.target.closest('.delete-btn'); if (!deleteBtn || !listContainer.contains(deleteBtn)) return; deleteItem(deleteBtn.dataset.id); }); 형태로 작성합니다. 이렇게 하면 버튼 내부에 아이콘(svg, i 태그)이나 텍스트 스팬이 들어있어 e.target이 버튼 자식 요소를 가리키더라도 정확하게 의도한 버튼 요소를 찾아 동작을 수행할 수 있습니다.

javascript-event-delegation-closest-pattern-implementation

메모리 누수 방지와 유지보수를 위한 재발 방지 수칙

동적 요소를 다룰 때 흔히 범하는 실수 중 하나는 목록을 새로 그릴 때마다 기존 요소와 새 요소를 구분하지 않고 전체 목록에 이벤트 리스너를 계속해서 다시 등록하는 방식입니다. 이는 동일 요소에 리스너가 중복 바인딩되어 한 번의 클릭에 함수가 여러 번 실행되는 부작용을 일으키며, 참조가 해제되지 않아 브라우저 메모리 누수로 이어집니다. 따라서 동적 목록 영역은 예외 없이 상위 컨테이너 기반의 이벤트 위임 구조로 단일화하는 것이 안전합니다.

또한 상위 컨테이너가 교체되지 않는 고정된 DOM 노드인지 확인해야 합니다. 만약 innerHTML로 컨테이너 자체의 내부 전체를 통째로 비우고 재구성한다면 컨테이너 하위의 위임 처리 역시 끊길 수 있으므로, 데이터 갱신 영역과 고정 래퍼 영역의 구조를 명확히 분리해야 합니다. 아울러 자식 요소 내부에서 event.stopPropagation()을 무분별하게 호출하면 상위로의 버블링이 차단되어 위임 리스너가 동작하지 않으므로 전파 중단 메서드 사용은 신중하게 제한해야 합니다.

preventing-memory-leak-and-duplicate-event-listeners
조회 14