정의 및 사용 방법

insertAdjacentElement() 함수는
지정된 요소의 인접한(Adjacent) 특정 위치에 하나의 DOM 요소 노드를 직접 삽입(insert)합니다.

구문

insertAdjacentElement() 함수는 지정된 요소(element)의 인접한 위치에(position) 전달받은 DOM 요소 노드(newElement)를 직접 삽입합니다.

JavaScript 
element.insertAdjacentElement(position, newElement)

element는 insertAdjacentElement() 함수를 적용할 지정된 요소입니다.

다음은 노드(Node) 용어에 대한 간단한 부연설명입니다.
노드(Node)
HTML DOM은 노드의 집합체입니다.
HTML에서 말하는 요소는 "요소 노드"를 의미하며,
텍스트는 "텍스트 노드",
주석은 "주석 노드"라고 말합니다.

매개변수

insertAdjacentElement() 함수의 매개변수
position 지정된 요소의 인접한 위치를 나타내는 문자열입니다. 다음 문자열 중에서 하나이여야 합니다.
  • "beforebegin": 요소 바로 앞(부모 요소를 가지고 있을 때만 유효함)
  • "afterbegin": 요소 안쪽 시작 부분, 즉 첫 번째 자식으로 삽입
  • "beforeend": 요소 안쪽 끝 부분, 즉 마지막 자식으로 삽입
  • "afterend": 요소 바로 뒤(부모 요소를 가지고 있을 때만 유효함)
newElement 삽입할 요소 노드입니다. 새로 생성한 DOM 요소 객체 또는 기존의 DOM 요소 객체를 전달할 수 있습니다.

즉, 지정된 요소(element)의 인접한 위치

  • "beforebegin" (바로 앞)
  • "afterbegin" (안쪽 시작 부분)
  • "beforeend" (안쪽 끝 부분)
  • "afterend" (바로 뒤)

중 하나의 위치를 선택하여 DOM 요소 노드를 직접 삽입합니다.

insertAdjacentElement() 함수는 하나의 요소 노드(node) 트리(tree)를 지정된 위치에 삽입하는 역할을 합니다. 즉, 삽입하는 노드의 자손 요소 노드가 있을 경우에는 영향을 받지 않지만, 여러 개의 요소 노드 트리를 한 번에 삽입하는 것은 불가능합니다.

기본 예제

요소의 인접한 특정 위치를 시각화하면 다음과 같습니다.

HTML 요소의 인접한 특정 위치은 주석으로 나타냈습니다. 
<!-- beforebegin (바로 앞) -->
<div id="my-div" style="background: gold;"> <!-- 지정된 요소 -->
    <!-- afterbegin (안쪽 시작 부분) -->
    Content
    <!-- beforeend (안쪽 끝 부분)-->
</div>
<!-- afterend (바로 뒤) -->
JavaScript 
const ele = document.getElementById("my-div"); // 지정된 요소(element)

// 삽입할 요소
const newElement = document.createElement("p");
newElement.textContent = "삽입할 p 요소";

/*
 * element.insertAdjacentElement(position, newElement)
 * 지정된 요소(element)의
 * 인접한 위치에(position) 전달받은
 * DOM 요소 노드(newElement)를 직접 삽입합니다.
*/

// 요소 바로 앞 새로운 요소 삽입
// 하나의 요소 노드만을 삽입할 수 있음
ele.insertAdjacentElement("beforebegin", newElement); // 여러 개의 요소 노드 트리를 한 번에 삽입하는 것은 불가능
ele.insertAdjacentElement("afterbegin", newElement); // 여러 개를 삽입 시도 시 마지막 삽입만 가능

코드 부연설명
getElementById() 함수는 주어진 문자열과 값이 일치하는 id 속성의 값을 가진 요소 객체를 반환합니다.

코드 부연설명
createElement() 함수는 새로운 HTML 요소를 생성해서 반환합니다.

실제 적용된 모습

insertAdjacentHTML() 함수는 HTML 문자열을 DOM 요소로 변환하여 삽입하지만, insertAdjacentElement() 함수는 문자열이 아닌 자바스크립트로 "새로 생성한 DOM 요소"이거나 "이미 존재하는 DOM 요소"를 직접 삽입합니다.

자바스크립트로 "새로 생성한 DOM 요소"가 아닌 문서에 "이미 존재하는 DOM 요소"를 insertAdjacentElement() 함수로 삽입할 경우, 해당 요소는 기존 위치에서 삽입되는 위치로 이동합니다.

반환 값

삽입된 DOM 요소를 반환합니다. 만약 삽입이 실패하면 null을 반환합니다.

예외

insertAdjacentElement() 함수는 다음의 경우에 예외를 발생시킵니다.

SyntaxError

position이 지정된 문자열("beforebegin", "afterbegin", "beforeend", "afterend")이 아닌 경우 SyntaxError를 던집니다.

TypeError

삽입할 요소 노드(newElement)가 유효하지 않을 경우 TypeError를 던집니다.

insertAdjacentElement()와 insertAdjacentHTML() 차이

insertAdjacentElement() 와 insertAdjacentHTML()은 둘 다 지정된 요소의 인접한 위치에 새로운 콘텐츠를 삽입하는 함수이지만, 삽입되는 콘텐츠의 형태가 다릅니다. 차이점은 다음과 같습니다.

insertAdjacentElement()

  • 사용 목적: DOM 요소를 삽입.
  • 동작 방식: 이미 존재하는 DOM 요소(예: document.createElement()로 만든 요소나 기존의 DOM 요소)를 특정 위치에 직접 삽입합니다.
JavaScript 
const newElement = document.createElement("div");
element.insertAdjacentElement("beforeend", newElement);

여기서 새로 생성한 <div> 요소가 특정 위치에 삽입됩니다.

주요 특징
  • DOM 요소를 직접 삽입하므로, 삽입할 때 DOM 객체가 필요.
  • HTML 문자열이 아닌, 하나의 요소 노드만을 삽입할 수 있음.

insertAdjacentHTML()

  • 사용 목적: HTML 코드 문자열을 삽입.
  • 동작 방식: 전달된 HTML 문자열을 해석(parsing)해서 DOM에 요소로 변환하고, 해당 위치에 삽입합니다.
JavaScript 
element.insertAdjacentHTML("beforeend", '<div class="new-element">New Element</div>');

여기서 <div> 요소가 해석되어 실제 DOM에 추가됩니다.

주요 특징
  • HTML 문자열이 그대로 DOM 요소로 변환되어 삽입됨.
  • 여러 요소 노드를 HTML 문자열에 추가할 수 있으므로, 여러 요소 노드 트리를 삽입할 수 있음

insertAdjacentElement()와 insertAdjacentHTML() 비교

insertAdjacentElement()와 insertAdjacentHTML() 비교
특징 insertAdjacentElement() insertAdjacentElement()
삽입 값 이미 생성된 노드 HTML 문자열
요소 노드 하나의 요소 노드 트리만 삽입할 수 있음. 즉, 삽입하는 노드의 자손 요소 노드는 영향을 받지 않지만, 여러 개의 요소 노드 트리를 한 번에 삽입하는 것은 불가능 여러 요소 노드를 HTML 문자열에 추가할 수 있으므로, 여러 요소 노드 트리를 삽입할 수 있음
성능 DOM 요소가 직접 삽입되기 때문에 상대적으로 빠름 문자열을 HTML로 해석(parsing)해서 DOM 요소를 변환하기 때문에 상대적으로 느림
요소 삽입 시 복잡성 insertAdjacentElement()보다 상대적으로 복잡함 HTML 코드를 문자열로 삽입하기 때문에 상대적으로 직관적이며, 복잡하지 않음
보안적인 측면 상대적으로 위험성이 적음 HTML 문자열을 그대로 파싱하여 DOM에 삽입하므로, 사용자 입력을 직접 삽입하는 경우 등 제어할 수 없는 문자열을 설정할 때에는 보안적인 측면을 항상 고려해야 함.

이 두 함수는 삽입하려는 데이터의 형식이 다르기 때문에, 상황에 따라 적절한 함수를 사용해야 합니다.

예제

상황에 따라 insertAdjacentElement()를 사용해서 요소를 삽입하는 예제입니다.

자바스크립트로 생성한 DOM 요소 노드를 삽입하기

다음은 document.createElement()로 만든 요소를 지정한 요소의 특정 위치에 삽입하는 예제입니다.

HTML 요소의 인접한 특정 위치은 주석으로 나타냈습니다. 
<!-- beforebegin (바로 앞) -->
<div id="my-div" style="border: 1px solid red; margin-bottom: 1em;">
    <!-- afterbegin (안쪽 시작 부분) -->
    Content
    <!-- beforeend (안쪽 끝 부분)-->
</div>
<!-- afterend (바로 뒤) -->
<button type="button" id="insert-btn">div 바로 앞에 요소 삽입하기</button>
JavaScript 
const btn = document.getElementById("insert-btn");          

btn.addEventListener("click", () => {
    // 지정된 요소
    const myDiv = document.getElementById("my-div");

    if (myDiv) {
        // 삽입할 요소
        const newElement = document.createElement("p");
        newElement.textContent = "새로운 텍스트";

        // 요소 바로 앞 새로운 요소 삽입
        myDiv.insertAdjacentElement("beforebegin", newElement);
    }
});

코드 부연설명
createElement() 함수는 새로운 HTML 요소를 생성해서 반환합니다.

실제 적용된 모습 '버튼'을 실제로 클릭해 보세요!

기존 요소 이동하기

문서에 있는 기존 요소를 insertAdjacentElement()로 삽입할 경우, 해당 요소는 기존 위치에서 삽입되는 위치로 이동합니다.

이는 문서상 DOM에서 하나의 요소 노드는 한 위치에만 존재할 수 있기 때문입니다. 즉, 복사본이 생성되지 않고, 그 요소 노드가 새로운 위치로 이동하는 것입니다.

만약 기존에 있는 DOM 요소를 다른 위치로 옮긴다면 아래와 같은 방식으로 할 수 있습니다.

HTML 요소의 인접한 특정 위치은 주석으로 나타냈습니다. 
<div id="first" style="background-color: gold;">첫 번째 요소</div>
<div id="second">두 번째 요소</div>

<!-- beforebegin (바로 앞) -->
<div id="my-div" style="border: 1px solid red;margin-bottom: 1em;">
    <!-- afterbegin (안쪽 시작 부분) -->
    Content
    <!-- beforeend (안쪽 끝 부분)-->
</div>
<!-- afterend (바로 뒤) -->
<button type="button" id="insert-btn">div 안쪽 끝 부분에 기존 요소 이동하기</button>
JavaScript 
const btn = document.getElementById("insert-btn");          

btn.addEventListener("click", () => {
    // 지정된 요소
    const myDiv = document.getElementById("my-div");

    if (myDiv) {
        // 기존 DOM 요소 가져오기
        const firstElement = document.getElementById("first");

        // 요소 안쪽 끝 부분에 기존 요소 이동
        myDiv.insertAdjacentElement("beforeend", firstElement);
    }
});
실제 적용된 모습 '버튼'을 실제로 클릭해 보세요!

여러 요소 노드 삽입하기

insertAdjacentElement() 함수는 이미 생성된 하나의 노드(node) 트리(tree)를 지정된 위치에 삽입하는 역할을 합니다. 즉, 여러 개의 요소 노드 트리를 한 번에 삽입하는 것은 불가능합니다.

여러 요소를 한 번에 삽입하려면 반복문을 사용하거나, 문서 조각(Document Fragment)을 이용하는 등의 추가적인 작업이 필요합니다.

여기에서는 삽입할 요소들을 배열에 담아 반복문으로 순회하면서 insertAdjacentElement()를 호출하는 예제를 다룹니다.

HTML 요소의 인접한 특정 위치은 주석으로 나타냈습니다. 
<!-- beforebegin (바로 앞) -->
<div id="my-div" style="border: 1px solid red;margin-bottom: 1em;">
    <!-- afterbegin (안쪽 시작 부분) -->
    Content
    <!-- beforeend (안쪽 끝 부분)-->
</div>
<!-- afterend (바로 뒤) -->
<button type="button" id="insert-btn">여러 요소 삽입하기</button>
JavaScript 
const btn = document.getElementById("insert-btn");          

btn.addEventListener("click", () => {
    // 지정된 요소
    const myDiv = document.getElementById("my-div");

    if (myDiv) {
        // 삽입할 여러 요소를 생성하기
        const elH3 = document.createElement("h3");
        elH3.textContent = "새로운 h3 요소";

        const elP = document.createElement("p");
        elP.textContent = "새로운 p 요소";

        const elDiv = document.createElement("div");
        elDiv.textContent = "새로운 div 요소";

        // 삽입할 여러 요소를 배열에 담기
        const elements = [
            elH3,
            elP,
            elDiv
        ];

        // 반복문으로 순회하면서 호출하기
        elements.forEach(element => {
            myDiv.insertAdjacentElement("beforebegin", element);
        });
    }
});
실제 적용된 모습 '버튼'을 실제로 클릭해 보세요!

insertAdjacentElement()는 DOM을 조작할 때 더 엄격한 제약이 있으며, 여러 요소를 한 번에 삽입할 수 없는 점이 성능이나 편리함에 영향을 미칠 수 있습니다. 개발자는 이 특성을 이해하고 상황에 맞게 적절한 함수를 선택해야 합니다.

브라우저 호환성

insertAdjacentElement() 함수의 브라우저 호환성
메서드
데스크탑 Chrome
Chrome
데스크탑데스크탑 Edge
Edge
데스크탑 Firefox
Firefox
Safari
Safari
insertAdjacentElement() 1 17 78 3

명세서

insertAdjacentElement() 함수의 명세서 사양
명세서 사양
insertAdjacentElement() DOM Standard
#dom-element-insertadjacentelement

참고문헌

같이 보기