범위가 지정된 레지스트리를 사용하여 맞춤 요소가 작동하도록 하기

Jayson Chen

Patrick Brosset

게시일: 2026년 3월 9일

맞춤 요소를 사용하면 웹 앱 개발자가 고유한 동작으로 UI 구성요소를 빌드, 공유, 재사용하여 개발을 더 쉽게 할 수 있습니다. 하지만 앱에서 서로 다른 맞춤 요소 집합을 함께 가져오면 문제가 발생할 수 있으며 이름 충돌이 발생할 수 있습니다. 범위가 지정된 맞춤 요소 레지스트리가 이 문제를 해결합니다.

Microsoft Edge팀에서 이 기능을 개발했으며, 이제 Edge 및 Chrome 146과 기타 Chromium 기반 브라우저에서 범위가 지정된 맞춤 요소 레지스트리를 기본적으로 사용할 수 있게 되었습니다. 이제 맞춤 요소를 캡슐화하여 구성요소 및 마이크로 프런트엔드 라이브러리 개발자의 오랜 문제를 해결할 수 있습니다.

범위가 지정된 맞춤 요소 레지스트리는 웹 개발자에게 중요한 패턴을 제공합니다. 이제 여러 팀에서 독립적으로 개발한 여러 맞춤 요소 라이브러리 또는 동일한 라이브러리의 여러 버전을 나란히 사용할 수 있습니다.

범위가 지정된 맞춤 요소 레지스트리란 무엇인가요?

현재 웹페이지의 모든 맞춤 요소 정의는 window.customElements의 단일 공유 레지스트리에 있습니다. 즉, 서로 다른 두 라이브러리에서 모두 <my-button>과 같은 동일한 태그 이름으로 맞춤 요소를 정의하려고 하면 오류가 발생하고 페이지가 중단됩니다. 이는 실제 세계에서 심각한 문제입니다. 여러 팀, 디자인 시스템 또는 마이크로 프런트엔드에서 사용자 인터페이스를 구성하는 대규모 애플리케이션은 이름 충돌이 발생하기 쉽습니다. 범위가 지정된 맞춤 요소 레지스트리를 사용하면 독립 레지스트리를 만들어 이 문제를 해결할 수 있습니다. 각 레지스트리는 전역 레지스트리 및 서로 완전히 격리된 자체 맞춤 요소 정의 집합을 유지합니다.

새 레지스트리 만들기

전역 window.customElements 레지스트리에 모든 맞춤 요소를 정의하는 대신 다음을 수행하세요.

1. new CustomElementRegistry()를 호출하여 새 레지스트리를 만듭니다.
2. 새 레지스트리에 특정 범위를 지정합니다 (레지스트리 범위 지정 참고).
3. 새 레지스트리에 포함될 요소를 정의합니다.

그런 다음 맞춤 요소를 사용하면 브라우저가 연결된 레지스트리(반드시 전역 레지스트리가 아님)에서 요소의 정의를 조회합니다. 즉, 페이지의 여러 부분에서 완전히 다른 맞춤 요소 정의 세트를 사용할 수 있습니다.

레지스트리 범위 지정

맞춤 요소 레지스트리는 문서, 섀도우 루트 또는 개별 요소로 범위가 지정될 수 있습니다.

섀도우 루트 범위

새 레지스트리를 섀도우 루트로 범위 지정하려면 attachShadow() 메서드를 호출할 때 customElementRegistry 옵션을 사용합니다. 이제 섀도우 루트 내에 있는 모든 맞춤 요소가 해당 범위가 지정된 레지스트리에 있는 정의를 사용합니다.

// Create your custom registry.
const registry = new CustomElementRegistry();
// Define a custom element in the new registry.
registry.define('my-card', class extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hello from scoped registry!';
  }
});

// Create shadow root, providing it with your new custom element registry.
const host = document.querySelector('#host');
const shadow = host.attachShadow({
  mode: 'open',
  customElementRegistry: registry,
});

shadow.innerHTML = '<my-card></my-card>';

선언적 섀도우 DOM

<template> 요소에서 shadowrootcustomelementregistry 속성을 사용하여 결과 섀도우 루트가 전역 레지스트리가 아닌 범위가 지정된 레지스트리를 사용한다고 브라우저에 알립니다.

<my-host>
  <template shadowrootmode="open" shadowrootcustomelementregistry>
    <my-widget></my-widget>
  </template>
</my-host>

  const registry = new CustomElementRegistry();
  registry.define('my-widget', class extends HTMLElement {
    connectedCallback() { this.textContent = 'Scoped!'; }
  });

  const shadow = document.querySelector('my-host').shadowRoot;
  registry.initialize(shadow);

예에 표시된 것처럼 속성은 맞춤 요소 레지스트리를 위한 공간을 예약하며, 사용자는 연결이 끊긴 문서에 섀도우 루트 범위를 지정하는 레지스트리를 정의하고 초기화해야 합니다.

document.implementation.createHTMLDocument()로 만든 문서와 같은 문서에 레지스트리를 범위 지정할 수도 있습니다. 이를 통해 <template> 요소를 클론하고 오프스크린 문서 조작을 실행할 수 있으며, 각 요소는 자체적으로 격리된 구성요소 정의 집합을 갖습니다. 이렇게 하려면 CustomElementRegistry.initialize() 메서드를 사용합니다.

// Create a new registry.
const registry = new CustomElementRegistry();
registry.define('app-widget', AppWidget);

// Create a document, and use registry.initialize() to scope the registry to the document.
const doc = document.implementation.createHTMLDocument('');
registry.initialize(doc);

doc.body.innerHTML = '<app-widget></app-widget>';

개별 요소로 범위 지정

customElementRegistry 옵션을 document.createElement()에 전달하여 레지스트리를 요소 및 하위 트리에 직접 연결할 수도 있습니다. 요소와 그 하위 요소는 나중에 DOM의 어느 부분에 삽입되든 해당 레지스트리에 대해 확인됩니다.

// Create a registry and define a custom element in it.
const registry = new CustomElementRegistry();
registry.define('fancy-label', FancyLabel);

// Create a new DOM element and scope the new registry to it.
const el = document.createElement('fancy-input', {
  customElementRegistry: registry,
});

// Use a custom element in the new DOM element.
el.innerHTML = '<fancy-label>Name</fancy-label>';

자세히 알아보기

자세한 내용은 Edge 데모와 소스 코드를 확인하고 MDN의 CustomElementRegistry 참조 문서를 참고하세요.

이제 Chromium 프로젝트를 통한 공동작업 덕분에 Microsoft Edge와 Chrome은 물론 다른 Chromium 기반 브라우저에서도 범위가 지정된 맞춤 요소 레지스트리가 기본적으로 사용 설정됩니다.

설정을 사용 설정하거나 오리진 트라이얼에 가입할 필요가 없습니다. Chromium 기반 브라우저에서 오늘 바로 이 기능을 사용할 수 있습니다.

다른 브라우저에서 이 기능을 구현해야 하는 경우 범위가 지정된 맞춤 요소 등록소 문제에 좋아요 반응을 남기고 사용 사례와 해결 방법을 댓글로 남겨 주세요.

Chromium 기반 브라우저에서 기능 구현에 버그가 발견되면 crbug.com/new에서 문제를 열어 조사할 수 있도록 하세요.

범위가 지정된 맞춤 요소 레지스트리를 통해 웹 구성요소를 더 쉽게 사용할 수 있기를 바랍니다.