Membuat elemen kustom berperilaku dengan registry cakupan

Jayson Chen

Patrick Brosset

Dipublikasikan: 9 Maret 2026

Elemen kustom memungkinkan developer aplikasi web membuat, membagikan, dan menggunakan kembali komponen UI dengan perilaku uniknya, sehingga mempermudah pengembangan. Namun, saat aplikasi Anda menggabungkan berbagai set elemen kustom, semuanya bisa menjadi berantakan, dan konflik nama dapat terjadi. Pendaftaran elemen kustom yang tercakup menyelesaikan masalah ini.

Tim Microsoft Edge telah mengerjakan fitur ini, dan dengan senang hati kami mengumumkan bahwa pendaftaran elemen kustom yang tercakup kini tersedia secara default dari Edge dan Chrome 146, serta browser berbasis Chromium lainnya. Anda kini dapat mengenkapsulasi elemen kustom, sehingga mengatasi masalah yang sudah lama dihadapi developer komponen dan pustaka micro-frontend.

Pendaftaran elemen kustom yang tercakup membuka pola penting bagi developer web. Sekarang, Anda dapat menggunakan beberapa library elemen kustom, yang dikembangkan secara independen oleh beberapa tim, atau beberapa versi dari library yang sama secara berdampingan.

Apa yang dimaksud dengan pendaftaran elemen kustom cakupan?

Saat ini, setiap definisi elemen kustom di halaman web berada dalam satu registri bersama di window.customElements. Artinya, jika dua pustaka yang berbeda mencoba menentukan elemen kustom dengan nama tag yang sama, seperti <my-button>, error akan ditampilkan dan halaman akan rusak. Ini adalah masalah yang signifikan di dunia nyata. Aplikasi besar yang menyusun antarmuka penggunanya dari beberapa tim, sistem desain, atau micro-frontend dapat dengan mudah mengalami konflik penamaan. Pendaftaran elemen kustom yang tercakup memecahkan masalah ini dengan memungkinkan Anda membuat pendaftaran independen. Setiap pendaftaran mempertahankan kumpulan definisi elemen kustomnya sendiri, yang sepenuhnya terisolasi dari pendaftaran global dan satu sama lain.

Membuat registri baru

Daripada menentukan setiap elemen kustom dalam pendaftaran window.customElements global:

1. Buat registri baru dengan memanggil new CustomElementRegistry().
2. Berikan cakupan spesifik untuk registri baru Anda (lihat Mencakup registri Anda).
3. Tentukan elemen yang masuk ke registri baru.

Kemudian, saat elemen kustom digunakan, browser akan mencari definisi elemen dari registry terkait, yang belum tentu merupakan registry global. Artinya, berbagai bagian halaman Anda dapat menggunakan kumpulan definisi elemen kustom yang sama sekali berbeda.

Mencakup registry Anda

Pendaftaran elemen kustom dapat dicakup ke dokumen, root shadow, atau elemen individual.

Mencakup ke root bayangan

Untuk mencakup cakupan registri baru ke root shadow, gunakan opsi customElementRegistry saat memanggil metode attachShadow(). Semua elemen kustom yang ada di dalam shadow root tersebut kini akan menggunakan definisi yang ada di registry cakupan yang sesuai:

// 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>';

Shadow DOM deklaratif

Gunakan atribut shadowrootcustomelementregistry pada elemen <template> untuk memberi tahu browser bahwa shadow root yang dihasilkan menggunakan registry yang tercakup, bukan yang global:

<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);

Seperti yang ditunjukkan dalam contoh, atribut mencadangkan ruang untuk pendaftaran elemen kustom, dan pengguna perlu menentukan serta menginisialisasi pendaftaran untuk cakupan root shadow ke dokumen yang terputus

Anda juga dapat mencakup cakupan registri ke dokumen, seperti yang dibuat oleh document.implementation.createHTMLDocument(). Hal ini memungkinkan Anda meng-clone elemen <template>, dan melakukan manipulasi dokumen di luar layar, masing-masing dengan kumpulan definisi komponen yang terisolasi. Untuk melakukannya, gunakan metode 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>';

Mencakup elemen individual

Anda juga dapat mengaitkan registry secara langsung dengan elemen dan subpohonnya dengan meneruskan opsi customElementRegistry ke document.createElement(). Elemen dan turunannya akan di-resolve terhadap registry tersebut, terlepas dari bagian DOM mana pun yang akan dimasukkan nanti:

// 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>';

Pelajari lebih lanjut

Untuk mempelajari lebih lanjut, lihat demo Edge dan kode sumbernya, serta baca artikel referensi CustomElementRegistry MDN

Pendaftaran elemen kustom yang tercakup kini diaktifkan secara default di Microsoft Edge dan Chrome, serta di browser berbasis Chromium lainnya, berkat kolaborasi kami melalui project Chromium.

Anda tidak perlu mengaktifkan setelan apa pun atau mendaftar ke uji coba origin. Anda dapat mulai menggunakan fitur ini sekarang di browser berbasis Chromium.

Jika Anda ingin fitur ini diterapkan di browser lain, berikan reaksi suka pada masalah Pendaftaran elemen kustom yang tercakup, dan berikan komentar dengan kasus penggunaan dan solusi Anda.

Jika Anda menemukan bug pada penerapan fitur di browser berbasis Chromium, buka masalah agar kami dapat menyelidikinya di crbug.com/new.

Kami berharap pendaftaran elemen kustom yang tercakup akan mempermudah penggunaan komponen web.