Orientasi Komponen Web

Komponen Web adalah Elemen Kustom, Shadow DOM, dan Template HTML: primitif platform untuk komponen yang dapat digunakan kembali dan tidak bergantung pada framework, yang markup dan gayanya dienkapsulasi dari dokumen. Gunakan elemen kustom untuk sistem desain, widget yang dapat disematkan, dan UI mandiri.

Aturan di bawah ini bersifat lintas sektoral. Ambil panduan spesifik untuk tugas yang sedang dikerjakan; setiap panduan menyatakan kembali konteks yang diperlukan dan mendokumentasikan API serta masalah yang unik untuk tugas tersebut.

Memutuskan apakah Anda memerlukan elemen kustom

Gunakan elemen kustom hanya saat Anda memerlukan perilaku, siklus proses, atau API yang didukung JS yang dapat digunakan kembali pada tag. Jangan buat jika:

• Elemen HTML biasa dengan CSS sudah cukup. <button> atau <details> yang diberi gaya lebih mudah diakses dan lebih murah daripada penerapan ulang.
• Hal ini murni bersifat presentasi tanpa perilaku. Class pada elemen native memiliki performa yang lebih baik, dan dapat dicakup dengan @layer atau @scope.
• Anda hanya memerlukan cakupan gaya di server tanpa interaktivitas; stylesheet tercakup atau Declarative Shadow DOM (tanpa upgrade) mungkin sudah cukup.

Membangun ulang semantik native (<my-button> kustom yang membuat ulang fokus, aktivasi, dan ARIA) adalah penyalahgunaan yang paling umum: Anda mewarisi aksesibilitas platform secara gratis hanya jika Anda menggunakan kembali elemen native. Jika wrapper bergaya <my-button> diperlukan — biasanya untuk hook gaya bersama, markup tambahan, atau perilaku yang tidak dapat diekspresikan oleh elemen native — gabungkan <button> yang sebenarnya, bukan mengimplementasikannya kembali (lihat Menata Gaya Komponen Web untuk meneruskan gaya ke elemen native internal).

Pengujiannya adalah apakah Anda memerlukan status yang dienkapsulasi, API yang dapat ditulis skrip, atau perilaku yang tidak dapat diekspresikan oleh elemen native — bukan sekadar tampilan yang berbeda. Tombol suka/favorit memenuhi syarat: tombol ini membawa status domain yang terkunci, mengekspos status tersebut sebagai hook gaya untuk halaman di sekitarnya, dan mengirimkan peristiwa change-nya sendiri — tidak ada yang diberikan oleh <button> yang diberi gaya. Tombol yang hanya berubah warna saat ditekan tidak: gunakan <button> + CSS. Saat Anda membuatnya, buat model statusnya dengan status atau atribut kustom yang sesuai (lihat Elemen Kustom).

Mencocokkan alat dengan codebase

Apakah sesuatu harus menjadi elemen kustom bergantung pada apa yang sudah digunakan project. Agen cenderung melakukan abstraksi berlebihan dan terlalu bersemangat menggunakan elemen baru — jika ragu, opsi yang lebih ringan (elemen native, CSS, template server) biasanya tepat, dan Anda dapat mengupgrade ke elemen kustom nanti jika penggunaan ulang atau perilaku benar-benar membutuhkannya. Heuristik, dalam prioritas kasar:

• Codebase sudah memiliki model komponen (React, Vue, Svelte, …). Gunakan komponen framework tersebut secara default untuk UI dalam aplikasi. Gunakan elemen kustom hanya jika elemen tersebut harus keluar atau bertahan lebih lama dari framework: primitif sistem desain yang digunakan bersama di seluruh aplikasi atau framework, widget yang dimasukkan ke dalam markup yang tidak dikontrol framework, atau output yang harus berfungsi sebagai HTML biasa (email, CMS, fragmen SSR). Jangan menyiapkan sistem komponen paralel untuk tampilan dalam aplikasi biasa.
• Tidak ada alat, sebagian besar markup statis. Lebih memilih HTML + CSS biasa, atau template/parsial server. Elemen kustom hanya berguna jika Anda benar-benar memerlukan perilaku, siklus proses, atau API yang didukung JS pada tag — bukan sekadar untuk berbagi markup, yang dilakukan oleh penyertaan server atau <template> tanpa mengirimkan JS apa pun.
• Generator situs statis dengan pulau interaktivitas. Render markup secara statis; simpan elemen kustom untuk bagian interaktif. Untuk "banyak markup, sedikit interaktivitas", pertahankan markup di Light DOM (atau Shadow DOM Deklaratif) dan biarkan elemen kustom kecil meningkatkannya secara progresif, daripada merender ulang semuanya dari JS.
• Sebagai gantinya, Anda dapat mendorong elemen bawaan lebih jauh. Menggunakan elemen native sejauh mungkin (CSS, beberapa pemroses, elemen pseudo sesekali) biasanya lebih disukai daripada elemen kustom, karena Anda mempertahankan aksesibilitas dan perilaku platform tanpa biaya. Beralihlah ke elemen kustom saat solusi tidak dapat lagi dipertahankan — saat Anda harus melawan perilaku bawaan elemen, atau pengalaman penulisan menjadi lebih buruk daripada API komponen yang bersih. Memerlukan sedikit JS pada elemen bawaan bukanlah alasan untuk menggantinya.

Aturan lintas sektoral

Hal ini berlaku untuk setiap panduan di bawah:

• WAJIB: nama tag harus menggunakan format kebab-case dengan setidaknya satu tanda hubung (misalnya, my-element). Hal ini membedakan elemen kustom dari elemen bawaan saat ini dan yang akan datang.
• WAJIB: panggil super() terlebih dahulu di konstruktor, sebelum menyentuh this; memanggilnya setelah pernyataan apa pun yang membaca atau menulis this akan menampilkan error.
• WAJIB: gunakan elemen semantik (<button>, <nav>, <ul>) di dalam template shadow. Sebagian besar kegagalan aksesibilitas di shadow tree berasal dari markup non-semantik; slot tidak mengubah peran dari apa yang diproyeksikannya.
• WAJIB: Referensi id ARIA (aria-labelledby, aria-describedby, aria-controls) tidak dapat melewati batas shadow; elemen referensi dan id yang ditunjuknya harus berada di hierarki yang sama.
• Pilih attachShadow({ mode: 'open' }) agar alat developer, skrip halaman, dan hidrasi server dapat menjangkau element.shadowRoot. Gunakan 'closed' hanya jika Anda harus menyembunyikan struktur internal dari skrip halaman.
• Hindari elemen bawaan yang disesuaikan (extends HTMLButtonElement dengan is="…"); Safari telah menolak secara permanen untuk mengirimkannya.

Matriks panduan kasus penggunaan

Identifikasi tugas dan ambil panduannya: