소프트웨어 및 오픈 소스

Web Components: Vanilla JavaScript로 재사용 가능한 UI 컴포넌트 만들기

Web Components: Build Reusable UI Components with Vanilla JavaScript

Web Components를 단계별로 학습하며 Custom Elements, Shadow DOM, HTML Templates, slots, JavaScript modules를 사용해 재사용 가능한 UI 카드를 만들어 보세요. 프레임워크나 빌드 도구는 필요 없습니다.

웹 구성 요소: vanilla JavaScript로 재사용 가능한 UI 구성 요소 만들기

websites용 카드를 만들었다고 가정해 봅시다. 그 카드를 WordPress 테마, Joomla 확장, 또는 독립형 애플리케이션에서 각 환경에 맞게 다시 작성하지 않고도 사용할 수 있다면?

바로 그 것이 Web Components의 약속이다: 재사용 가능한 HTML 요소를 만들기 위한 브라우저 네이티브 도구들. 우리가 만들 예정인 예제에서는 React, Vue, npm 패키지, 번들러가 필요하지 않다.

이 튜토리얼을 마치면, <ui-card> 구성 요소를 완성하게 된다. 이는 사용자 정의 내용, 격리된 스타일, 특별한 변형, dismiss 버튼, 공개 이벤트를 지원한다. 각 기여가 하는 역할을 알 수 있도록 단계별로 나누어 설명한다.

우리가 만들 것

완성된 구성 요소는 다음 HTML를 지원한다:

<ui-card variant="featured">
  <span slot="title">Learn Web Components</span>
  <p>Build reusable interfaces with native JavaScript.</p>
  <a slot="action" href="/tutorial">Read the tutorial</a>
</ui-card>

시각적 미리보기 - 표준 및 특별 카드

표준 및 특별 웹 구성 요소 카드의 시각적 미리보기

이 미리보기는 디자인 목표이며, 관련 없는 라이브러리의 스크린샷은 아니다. 우리는 아래의 코드를 사용하여 이를 재현할 것이다.

1. 네 가지 빌딩 블록 이해하기

Custom Elements는 새로운 HTML 태그크와 그 JavaScript 동작을 등록할 수 있게 한다. Shadow DOM은 요소가 자신의 내부 DOM과 스코프된 스타일을 가질 수 있게 한다. HTML 템플릿과 슬롯은 각 인스턴스에 다른 내용을 삽입하면서 구조를 재사용할 수 있게 한다. ES Modules는 일반 JavaScript 파일에서 구성을 로드할 수 있게 한다.

이들은 별도의 기능이다. Custom Element는 반드시 Shadow DOM을 사용할 필요는 없으며, 어떤 프레임워크도 없이도 이들을 사용할 수 있다.

2. 프로젝트 파일 만들기

에디터에서 다음 구조를 만든다:

web-components-demo/
├── index.html
├── components/
│   └── ui-card.js
└── css/
    └── main.css

이것을 index.html에 넣는다:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Web Components Demo</title>
  <link rel="stylesheet" href="./css/main.css">
  <script type="module" src="./components/ui-card.js"></script>
</head>
<body>
  <main class="container">
    <h1>Reusable UI Components</h1>
    <p>Let's build a reusable card without a framework.</p>
    <ui-card></ui-card>
  </main>
</body>
</html>

페이지 수준 스타일을 css/main.css에 추가한다:

body {
  margin: 0;
  background: #f4f6f9;
  color: #1f2937;
  font-family: system-ui, sans-serif;
}
.container {
  max-width: 900px;
  margin: 60px auto;
  padding: 0 20px;
}
ui-card {
  display: block;
  margin-top: 24px;
}

프로젝트 디렉터리에서 로컬 HTTP 서버를 실행한다, 예를 들어:

python -m http.server 8000

http://localhost:8000을 방문한다. 헤딩은 나타나지만, 카드에는 아직 보이지 않는 내용이 있다. index.html을 file://으로 여는 대신 HTTP 서버를 사용하는 것이 좋다: 브라우저 모듈 로드 규칙은 로컬 파일 import를 차단할 수 있다.

3. 첫 번째 Custom Element 등록하기

components/ui-card.js을 만든다:

class UiCard extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hello from a Web Component!';
  }
}

customElements.define('ui-card', UiCard);

페이지를 갱신한다. 이제 다음과 같이 보여야 한다:

기대 결과 - 단계 3

첫 번째 custom element 출력

HTMLElement은 일반 DOM 동작을 제공한다. connectedCallback()은 요소가 문서에 연결될 때 실행된다. customElements.define()은 HTML 태그와 класс를 연결한다.

ui-card의 하이phen은 자율적 Custom Element 이름에 필요하다. 요소가 분리된 후 다시 삽입되면 콜백이 다시 실행될 수 있으며, 초기화 로직을 추가할 때 중요하다.

4. Shadow DOM으로 카드에 고유 디자인 주기

ui-card.js을 다음으로 교체한다:

class UiCard extends HTMLElement {
  connectedCallback() {
    if (this.shadowRoot) return;

    const shadow = this.attachShadow({ mode: 'open' });

    shadow.innerHTML = `
      <style>
        article {
          padding: 24px;
          background: white;
          border: 1px solid #dce3ec;
          border-radius: 12px;
        }
        h2 {
          margin: 0 0 12px;
          color: #2563eb;
        }
      </style>
      <article>
        <h2>My reusable card</h2>
        <p>This content lives inside Shadow DOM.</p>
      </article>
    `;
  }
}

customElements.define('ui-card', UiCard);

기대 결과 - 단계 4

Shadow DOM 내부의 스타일링된 카드

DevTools를 열고, <ui-card>을 검사한 후 #shadow-root (open)을 펼친다. 내부 article과 스타일시트를 볼 수 있다.

일반 document 선택자와 달리, article { border: none }과 같은 전역 CSS는 일반적으로 이 shadow 트리에 도달하지 못한다. 상속된 속성과 CSS 사용자 정의 속성은 여전히 경계를 crossings할 수 있다. Shadow DOM은 프레SENTATION을 캡су화한다;但它은 보안 샌드박스가 아니다.

if (this.shadowRoot) 가드는 요소가 다시 연결될 경우 두 번째 shadow 루트를 붙이는 것을 방지한다.

5. HTML 템플릿으로 레이아웃 분리하기

구성 요소가 커지면 connectedCallback()에 모든 것을 내장하는 것은 불편해진다. 마크업을 한 번 정의하고, 각 카드에 대해 복제해 사용해 보자.

파일을 다음으로 교체한다:

const template = document.createElement('template');

template.innerHTML = `
  <style>
    article {
      padding: 24px;
      background: white;
      border: 1px solid #dce3ec;
      border-radius: 12px;
    }
    h2 {
      margin: 0 0 12px;
      color: #2563eb;
    }
  </style>
  <article>
    <h2>My reusable card</h2>
    <p>Created from an HTML template.</p>
  </article>
`;

class UiCard extends HTMLElement {
  connectedCallback() {
    if (this.shadowRoot) return;
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.appendChild(template.content.cloneNode(true));
  }
}

customElements.define('ui-card', UiCard);

template.content은 document fragment이다. cloneNode(true)은 전체 구조를 각 카드의 shadow 트리에 복사한다. 템플릿 자체는 클론하고 삽입하기 전까지 렌더링되지 않는다.

이 버전은 거의 동일해 보인다. 개선점은 아키텍처 차원이다: 하나의 템플릿으로 많은 인스턴스를 처리할 수 있다.

6. 슬롯을 사용하여 다른 내용 삽입하기

모든 인스턴스가 같은 헤딩을 가진다면 재사용 가능한 카드는 유용하지 않다. ui-card.js의 맨 위에 있는 -template 선언만 다음으로 교체한다; 5단계의클래 codes와 등록 코드는 그대로 유지한다.

const template = document.createElement('template');

template.innerHTML = `
  <style>
    article {
      padding: 24px;
      background: white;
      border: 1px solid #dce3ec;
      border-radius: 12px;
    }
    h2 { margin: 0 0 12px; color: #2563eb; }
    .content { line-height: 1.6; }
    .action { margin-top: 16px; }
  </style>
  <article>
    <h2><slot name="title">Untitled card</slot></h2>
    <div class="content"><slot></slot></div>
    <div class="action"><slot name="action"></slot></div>
  </article>
`;

이제 index.html의 <ui-card></ui-card>을 교체한다:

<ui-card>
  <span slot="title">Learn Web Components</span>
  <p>Build reusable interfaces with native JavaScript.</p>
  <a slot="action" href="/tutorial">Read the tutorial</a>
</ui-card>

기대 결과 - 단계 6

이름 있는 슬롯과 액션 링크가 있는 카드

이름 있는 슬롯은 slot="title"으로 표시된 요소를 받는다. 이름 없는 슬롯은 문단을 받는다. 액션 슬롯은 링크를 받는다. 슬롯에 할당된 내용이 없으면 폴백 텍스트가 나타난다.

레이아웃은 구성 요소에 존재하고, 실제 단어와 링크는 페이지의 HTML에 남는다. 이는 특히 CMS 내용에 유용하다. /tutorial을 프로젝트의 실제 대상으로 교체한다.

7. CSS로 특별한 변형 만들기

템플릿의 <style> 블록 내부에 추가한다:

:host {
  display: block;
}
:host([variant="featured"]) article {
  background: #eff6ff;
  border-color: #93c5fd;
}

그 다음 index.html의 단일 카드를 두 개의 카드로 교체한다:

<ui-card>
  <span slot="title">Standard card</span>
  <p>This card uses the default appearance.</p>
</ui-card>

<ui-card variant="featured">
  <span slot="title">Featured card</span>
  <p>This card has a highlighted appearance.</p>
</ui-card>

기대 결과 - 단계 7

표준 및 특별 카드 변형

이것은 :host()의 특히 유용한 기능이다: 사용자 정의 요소의 속성基础上 스타일을 적용한다. JavaScript가 나중에 variant을 변경하면 CSS가 자동으로 업데이트된다. 순수 CSS 기반 변경에는 attributeChangedCallback()이 필요하지 않다.

8. dismiss 버튼과 공개 이벤트 추가하기

카드를 인터랙티브로 만들어 보자. 템플릿의 <article> 내부에, 헤딩 앞에 이 버튼을 추가한다:

<button class="dismiss" type="button" aria-label="Dismiss card">
  ×
</button>

템플릿의 CSS에 다음 규칙을 추가한다:

article { position: relative; }
.dismiss {
  position: absolute;
  top: 12px;
  right: 12px;
  width: 32px;
  height: 32px;
  border: 0;
  border-radius: 6px;
  background: transparent;
  color: #475569;
  font-size: 24px;
  cursor: pointer;
}
.dismiss:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
}

클래 codes의 connectedCallback()을 다음으로 교체한다:

connectedCallback() {
  if (this.shadowRoot) return;

  const shadow = this.attachShadow({ mode: 'open' });
  shadow.appendChild(template.content.cloneNode(true));

  shadow.querySelector('.dismiss').addEventListener('click', () => {
    this.dispatchEvent(new CustomEvent('card-dismissed', {
      bubbles: true,
      composed: true
    }));
    this.remove();
  });
}

index.html에 </body> 앞에 이 스크립트를 추가한다:

<script type="module">
  document.addEventListener('card-dismissed', () => {
    console.log('A card was dismissed.');
  });
</script>

브라우저 콘솔을 열고 ×를 클릭한다. 카드가 사라지고 콘솔에 메시지가 표시된다.

이 이벤트는 공개 통합점을 제공한다: 주변 응용 프로그램은 카드 내부 버튼에 대해 알 필요가 없다. bubbles은 이벤트가 버블링하도록 하고, composed은 shadow 경계를 crossings할 수 있도록 허용한다 (해당되는 경우). 여기서 이벤트는 호스트 요소 자체에서 발생한다.

9. 완전한 최종 버전: 복사하여 사용하기

이제 components/ui-card.js의 전체 내용을 이 통합 버전으로 교체할 수 있다. 이는 이전 단계에서 구축된 동작을 유지하면서 CSS 사용자 정의와 내보낸 부분을 추가한다.

const template = document.createElement('template');

template.innerHTML = `
  <style>
    :host {
      display: block;
      color: #1f2937;
      font-family: system-ui, sans-serif;
    }
    article {
      position: relative;
      box-sizing: border-box;
      padding: 24px;
      background: var(--card-background, #fff);
      border: 1px solid var(--card-border, #dce3ec);
      border-radius: 12px;
    }
    :host([variant="featured"]) article {
      background: var(--card-featured-background, #eff6ff);
      border-color: var(--card-featured-border, #93c5fd);
    }
    h2 {
      margin: 0 36px 12px 0;
      color: var(--card-title-color, #2563eb);
      font-size: 1.25rem;
    }
    .content { line-height: 1.6; }
    .action { margin-top: 16px; }
    .dismiss {
      position: absolute;
      top: 12px;
      right: 12px;
      width: 32px;
      height: 32px;
      border: 0;
      border-radius: 6px;
      background: transparent;
      color: #475569;
      font-size: 24px;
      cursor: pointer;
    }
    .dismiss:hover { background: rgba(0, 0, 0, 0.06); }
    .dismiss:focus-visible {
      outline: 2px solid #2563eb;
      outline-offset: 2px;
    }
  </style>
  <article part="container">
    <button class="dismiss" type="button"
            aria-label="Dismiss card">×</button>
    <h2 part="title"><slot name="title">Untitled card</slot></h2>
    <div class="content"><slot></slot></div>
    <div class="action"><slot name="action"></slot></div>
  </article>
`;

class UiCard extends HTMLElement {
  connectedCallback() {
    if (this.shadowRoot) return;

    const shadow = this.attachShadow({ mode: 'open' });
    shadow.appendChild(template.content.cloneNode(true));

    shadow.querySelector('.dismiss').addEventListener('click', () => {
      this.dispatchEvent(new CustomEvent('card-dismissed', {
        bubbles: true,
        composed: true,
        detail: {
          variant: this.getAttribute('variant') || 'default'
        }
      }));
      this.remove();
    });
  }
}

if (!customElements.get('ui-card')) {
  customElements.define('ui-card', UiCard);
}

빠른 데모와 달리, 이 버전은 shadow 루트를 두 번 붙이려고 시도하지 않으며, innerHTML을 통해 신뢰할 수 없는 내용을 삽입하지 않으며, 프레임워크에 의존하지 않는다. 템플릿 문자열은 개발자 제어이다; 결코 신뢰할 수 없는 사용자 입력을 보간하지 마라.

10. 호스팅 웹 사이트에서 스타일링하기

Shadow DOM은 사용자 정의를 불가능하게 만드는 것은 아니다. 의도적인 스타일링 인터페이스를 정의하도록 유도한다.

css/main.css에 추가한다:

ui-card {
  --card-border: #cbd5e1;
  --card-title-color: #0f766e;
}
ui-card::part(container) {
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}

사용자 정의 속성은 shadow 트리에 상속되어我们 exposed된 값을 제어한다. part="container" 속성은 외부 CSS가 ::part(container)을 사용하여 선택된 내부 요소를 대상으로 할 수 있게 한다.

다른 특별 배경이 필요하면 --card-featured-background을 사용한다. 이는 소비자가 정확한 내부 DOM 구조에 의존하도록 강제하는 것보다 낫다.

11. WordPress, Joomla, 또는 일반 HTML에서 카드 재사용하기

ui-card.js을 대상 웹 사이트에 복사하고, JavaScript 모듈로 로드한다:

<script type="module" src="/assets/js/ui-card.js"></script>

그 다음 <ui-card>을 페이지 마크업에서 사용한다. WordPress에서는 테마 또는 플러그인의 지원 스크립트 로드 API를 통해 자산을 등록하며, WordPress 버전에 맞는 모듈 지원을 사용한다. Joomla에서는 Web Asset Manager를 사용하여 모듈을 등록하고 로드한다. 운영 템플릿에 하드코딩된 스크립트 태그를 흩어뜨리지 마라.

CMS가 생성한 카드의 경우, 제목, 문단, 링크를 슬롯된 HTML로 렌더링한다. CMS의 출력 규칙에 따라 내용과 속성을 이스케이프한다.

실적 이점: Joomla 모듈과 WordPress 블록은 동일한 사용자 정의 태그를 출력하면서 하나의 구성 요소 구현을 공유할 수 있다. 각 CMS는 자신의 내용을 가져오고 이스케이프하는 데 책임을진다.

12. 접근성, SEO, 점진적 향상

가능할 때마다 구성 요소 내부에 네이티브 HTML 컨트롤을 사용한다. dismiss 동작은 실제 button을 사용하며, 키보드 활성화 시맨틱을 제공한다. 또한 ×만으로는 설명적이지 않으므로 aria-label을 사용한다.

사용자가 키보드 포커스를 가진 상태에서 카드를 dismiss한 경우, 더 복잡한 인터페이스에서 포커스가 어디로 가야 할지 고려하라. 대화 상자, 메뉴, 콤보박스는 이 예제보다 더 많은 접근성 동작이 필요하다.

중요한 내용은 가능한 한 의미 있는 라이트-DOM 마크업에 유지한다. JavaScript가 실패하면 브라우저가 <ui-card>을 업그레이드하지 않을 것이지만, 슬롯된 헤딩과 문단은 문서에 남아 있을 것이다. 구성 요소의 스타일링된 셸과 dismiss 버튼은 존재하지 않을 것이다.

검색 엔진을 위해, JavaScript 전용 내용이 모든 크롤러에서 동일하게 색인되는 것이라고 가정하지 마라. 핵심 내용은 초기 HTML 또는 적절한 렌더링 전략을 통해 사용할 수 있어야 한다.

Shadow DOM에도 제한이 있다: 일반 document CSS 선택자는 내부 노드에 스타일을 적용할 수 없으며, 일부 ARIA ID 관계는 shadow 경계를 crossings할 수 없다. 구성 요소 API는這些 제한을 고려해 설계하라.

13. Web Components는 항상 더 빠른가?

반드시 아니다. Web Components는 특정 프레임워크 런타임을 요구하지 않지만, 성능은 JavaScript 양, DOM 복잡도, 렌더링 빈도, 애플리케이션 아키텍처에 따라 달라진다.

작은 카드는 좋은 후보다. 불필요한 DOM 재구성이 있는 수백 개의 복잡한 요소는 여전히 느릴 수 있다. 템플릿을 재사용하고, 반복된 전체 렌더링을 피하며, 실제 성능을 측정하라.

이미 프레임워크의 상태 관리와 라우팅으로 구축된 큰 애플리케이션의 경우, 해당 프레임워크의 own 구성 요소를 사용하는 것이 더 간단할 수 있다. Web Components는 안정적인 UI 요소가 프레임워크 또는 CMS 경계를 crossings할 때 빛을 발한다.

14. 문제 해결

증상 가능한 원인 확인할 것
카드가 비어 있다 모듈이 로드되지 않았다 DevTools 콘솔, URL, 서버 MIME 유형
customElements.define이 던진다 유효하지 않거나 중복된 이름 하이phen 요구사항 및 등록 가드
카드 내부에 CSS가 적용되지 않는다 Shadow DOM 경계 사용자 정의 속성, :host, 또는 ::part 사용
내용이 잘못된 자리에 나타난다 슬롯 이름 불일치 slot="title"과 <slot name="title"> 비교
dismiss 클릭이 아무것도 하지 않는다 템플릿 버튼 누락 shadow 트리와 콘솔 검사
구성 요소가 이동할 때 실패한다 초기화가 두 번 실행된다 shadow 루트 생성 가드
링크가 404를 lead 예제 URL이 교체되지 않았었다 존재하는 대상 사용

connectedCallback()은 한 번 이상 실행될 수 있다. 최종 예제의 가드는 초기화를 일次로 유지한다; 더 정교한 구성 요소는 연결 수명 주기 동안 외부 관찰자 또는 전역 이벤트 리스너를 붙이고 끊어야 할 수 있다.

15. 웹 구성 요소를 언제 사용해야 할까?

여러 웹 사이트, 프레임워크, 또는 CMS 환경에 걸쳐 재사용 가능한, 설명된 HTML 인터페이스가 필요한 구성 요소를 선택한다. 카드, 알림, 제품 위지트, 작은 인터랙티브 도구가 좋은 후보다.

일반 HTML과 CSS 몇 줄로 문제를 해결할 수 있다면 추상화를 생략하라. 강한 이유 없이는 네이티브 컨트롤을 재현하지 마라.

유용한 테스트: 다른 애플리케이션은 이 요소를 구현 방법을 알지 못하고 사용하는 데 이점이 될까? 만약 YES라면, Web Components를 고려할 가치가 있다.

결론

너는 브라우저 API에 대해 merely 읽은 것이 아니라, 실제 재사용 가능한 구성 요소를 만들었다. 사용자 정의 태그, 스코프된 스타일링, 구성 가능한 내용, 특별 변형, 다른 코드가 수 listens할 수 있는 이벤트를 가진다.

프로젝트에서 자주 나타나는 하나의 구성 요소로 시작하라. 작은 공개 API를 주고, 여러 레이아웃에서 테스트하며, 의존성을 최소한으로 유지하라.

Web Components의 장기적 가치는 모든 프레임워크를 대체하는 것并不而是, 그것이 처음 호스트한 프레임워크 또는 CMS보다 오래 살 수 있는 유용한 인터페이스 요소를 가능하게 한다는 점이다.

공식 참고 자료