Web Components: Bouw herbruikbare UI-componenten met Vanilla JavaScript
Leer Web Components stap voor stap door een herbruikbare UI-kaart te bouwen met Custom Elements, Shadow DOM, HTML Templates, slots en JavaScript-modules. Geen framework of build tools vereist.
Web Components: Maak herbruikbare UI-componenten met Vanilla JavaScript
Stel je voor om een kaart te maken voor je website en deze dan te gebruiken in een WordPress-thema, een Joomla-extensie of een standalone applicatie zonder deze voor elke omgeving opnieuw te schrijven.
Dat is de belofte van Web Components: browser-native tools voor het bouwen van herbruikbare HTML-elementen. Geen React, Vue, npm packages of bundler is nodig voor het voorbeeld dat we gaan bouwen.
Op het einde van deze tutorial heb je een werkende <ui-card> component met aanpasbare inhoud, geïsoleerde stijlen, een featured variant, een dismiss knop en een publieke event. We bouwen het in kleine stappen zodat je kunt zien wat elke technologie bijdragt.
Wat je gaat bouwen
Onze voltooide component zal deze HTML ondersteunen:
<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>
Visuele voorvertoning — standaard en featured cards
Deze preview is het designdoel, geen screenshot van een ongerelateerde bibliotheek. We reproduceren deze met de onderstaande code.
1. Begrijp de vier bouwstenen
Custom Elements stellen ons in staat om een nieuwe HTML-tag en zijn JavaScript gedrag te registreren. Shadow DOM geeft het element zijn eigen interne DOM en scoped stijlen. HTML templates en slots stellen ons in staat om de structuur te hergebruiken en tegelijkertijd verschillende inhoud in elke instantie in te voegen. ES Modules stellen ons in staat om de component vanuit een gewone JavaScript file te laden.
Dit zijn aparte functies. Een Custom Element hoeft geen Shadow DOM te gebruiken, en je hebt geen framework nodig om er een van te gebruiken.
2. Maak de projectbestanden
Maak deze structuur in je editor:
web-components-demo/
├── index.html
├── components/
│ └── ui-card.js
└── css/
└── main.css
Zet dit in 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>
Voeg de pagin-niveau stijlen toe aan 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;
}
Start een lokale HTTP server vanuit de projectmap, bijvoorbeeld:
python -m http.server 8000
Bezoek http://localhost:8000. De kop verschijnt, maar de kaart heeft nog geen zichtbare inhoud. Gebruik een HTTP server in plaats van index.html te openen met file://: browser regels voor het laden van modules kunnen lokale bestandsimports blokkeren.
3. Registreer je eerste Custom Element
Maak components/ui-card.js:
class UiCard extends HTMLElement {
connectedCallback() {
this.textContent = 'Hello from a Web Component!';
}
}
customElements.define('ui-card', UiCard);
Ververs de pagina. Je zou nu moeten zien:
Verwachte resultaat — Stap 3
HTMLElement levert normale DOM gedrag. connectedCallback() wordt uitgevoerd wanneer het element verbinding maakt met het document. customElements.define() koppelt de klasse aan de HTML-tag.
De koppelteken in ui-card is vereist voor autonome Custom Element namen. De callback kan opnieuw draaien als het element wordt losgekoppeld en opnieuw geplaatst, wat belangrijk is wanneer we initialisatie logica toevoegen.
4. Geef de kaart zijn eigen design met Shadow DOM
Vervang ui-card.js met:
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);
Verwachte resultaat — Stap 4
Open DevTools, inspecteer <ui-card> en vouwen #shadow-root (open) uit. Je ziet het interne artikel en stylesheet.
Ze verschillen van gewone document selectors. Globale CSS zoals article { border: none } bereikt dit doorgaans niet deze shadow tree. Geïnherente eigenschappen en CSS custom properties kunnen de grens nog wel overschrijden. Shadow DOM encapsuleert presentatie; het is geen beveiligingssandbox.
De if (this.shadowRoot) guard voorkomt het aankoppelen van een tweede shadow root als het element opnieuw verbinding maakt.
5. Scheid de lay-out met een HTML template
Het insluiten van alles in connectedCallback() wordt moeilijk naarmate een component groeit. Laten we de markup één keer definiëren en voor elke kaart kopiëren.
Vervang het bestand met:
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 is een document fragment. cloneNode(true) kopiëert de hele structuur naar de shadow tree van elke kaart. De template zelf rendert pas nadat we deze kopiëren en invoegen.
Deze versie ziet er bijna identiek uit. De verbetering is architectuur: één template kan vele doelinstanties dienen.
6. Voeg verschillende inhoud toe met slots
Een herbruikbare kaart is niet nuttig als elke instantie dezelfde kop heeft. Vervang alleen de template declaratie aan het begin van ui-card.js door de volgende; houd de klasse en registratiecode van stap 5.
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>
`;
Now vervang je <ui-card></ui-card> in index.html:
<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>
Verwachte resultaat — Stap 6
De benoemde slot ontvangt het gemarkeerde element slot="title". De niet-benoemde slot ontvangt de alinea. De actie slot ontvangt de link. De fallback tekst van een slot verschijnt als er niets aan is toegewezen.
De lay-out leeft in de component; de daadwerkelijke woorden en links blijven in de HTML van de pagina. Dit is vooral nuttig voor CMS inhoud. Vervang /tutorial door een echte bestemming in je project.
7. Maak een featured variant met CSS
In de template's <style> block, voeg toe:
:host {
display: block;
}
:host([variant="featured"]) article {
background: #eff6ff;
border-color: #93c5fd;
}
Vervang dan de enige kaart in index.html door twee kaarten:
<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>
Verwachte resultaat — Stap 7
Dit is een bijzondere nuttige functie van :host(): het stijlt de component op basis van attributen van de custom element. Als JavaScript variant later wijzigt, wordt de CSS automatisch bijgewerkt. Er is geen attributeChangedCallback() nodig voor een volledig CSS-gedreven wijziging.
8. Voeg een dismiss knop en een publieke event toe
Laten we de kaart interactief maken. Binnen de template's <article>, voeg deze knop voor de kop toe:
<button class="dismiss" type="button" aria-label="Dismiss card">
×
</button>
Voeg deze regels toe aan de CSS van de template:
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;
}
Vervang connectedCallback() in de klasse door:
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();
});
}
In index.html, voeg dit script toe vóór </body>:
<script type="module">
document.addEventListener('card-dismissed', () => {
console.log('A card was dismissed.');
});
</script>
Open de browser console en klik op ×. De kaart verdwijnt en de console toont het bericht.
Het event biedt een openbare integratie punt: de omringende applicatie hoeft niets te weten over de interne knop van de kaart. bubbles maakt het event bubble; composed staat toe om een shadow boundary te overschrijden waar van toepassing. Hier komt het event voort op het host element zelf.
9. Maak de complete finale versie: kopieer en gebruik
Je kunt nu de volledige inhoud van components/ui-card.js vervangen door deze geconsolideerde versie. Het voegt CSS aanpassingen en geëxporteerde onderdelen toe terwijl het gedrag uit de eerdere stappen behouden blijft.
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);
}
In tegenstelling tot een snelle demo probeert deze versie niet de shadow root twee keer bij te koppelen, voegt geen ongevalideerde inhoud toe met innerHTML en vertrouwt niet op een framework. De template string is developer-controlled; interpoler nooit onbeveiligde gebruikersinvoer in deze.
10. Styleer het vanaf de hostingwebsite
Shadow DOM is niet bedoeld om aanpassing onmogelijk te maken. Het moedigt je aan om een intentieke styling interface te definiëren.
In css/main.css, voeg toe:
ui-card {
--card-border: #cbd5e1;
--card-title-color: #0f766e;
}
ui-card::part(container) {
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}
De custom properties worden overgenomen door de shadow tree en controleren de waarden die we blootlegden. Het part="container" attribuut laat externe CSS een geselecteerd intern element targeten met ::part(container).
Als je een andere featured achtergrond nodig hebt, gebruik je --card-featured-background. Dit is beter dan het dwingen van consumenten om af te hangen van de exacte interne DOM structuur.
11. Hergebruik de kaart in WordPress, Joomla of plain HTML
Kopieer ui-card.js naar de doeltafel en laad het als een JavaScript module:
<script type="module" src="/assets/js/ui-card.js"></script>
Gebruik dan <ui-card> in de paginamarkeering. In WordPress registreer je assets via de theme of plugin's ondersteunde script-loading APIs, met module support passend bij je WordPress versie. In Joomla gebruik je de Web Asset Manager om het module te registreren en laden. Verspreid geen hardcoded script tags door productie templates.
Voor een CMS gegenereerde kaart, render de titel, alinea en link als slotted HTML. Escapen content en attributen volgens de output regels van de CMS.
Praktisch voordeel: een Joomla module en een WordPress block kunnen allebei dezelfde custom tag outputen terwijl ze één component implementatie delen. Elke CMS blijft verantwoordelijk voor het ophalen en escapen van eigen content.
12. Toegankelijkheid, SEO en progressive enhancement
Gebruik native HTML controls binnen componenten zoveel mogelijk. Onze dismiss actie gebruikt een echt button, dat toetsenbord activatie semantiek levert, en een aria-label omdat × alleen niet beschrijvend is.
Als een gebruiker een kaart dismissed met toetsenbord focus, overweeg dan waar focus de volgende stap zou moeten gaan in een complexere interface. Dialogen, menu's en comboboxes hebben veel meer toegankelijkheids gedrag dan dit voorbeeld.
Bewaar belangrijke content in betekenisvolle light-DOM markup waar praktisch. Als JavaScript faalt, wordt <ui-card> niet geüpgraded; de slotted kop en alinea blijven in het document, maar de gestijlde shell en dismiss knop van de component bestaan niet.
Voor zoekmachines, ga er niet van uit dat JavaScript-only inhoud in elke crawler op identieke wijze wordt geïndexeerd. Kritieke content moet beschikbaar zijn in de initiële HTML of door een passende rendering strategie.
Shadow DOM heeft ook beperkingen: gewone document CSS selectors stylen geen interne knopen, en sommige ARIA ID relaties kunnen geen shadow boundaries overschrijden. Ontwerp component APIs met die beperkingen in gedachten.
13. Zijn Web Components altijd sneller?
Nee, zijn Web Components altijd sneller?
Niet noodzakelijk. Web Components voorkomen dat een specifieke framework runtime vereist is, maar prestaties hangen af van de hoeveelheid JavaScript, DOM complexiteit, rendering frequentie en applicatie architectuur.
Een kleine kaart is een goede kandidaat. Honderden complexe elementen met onnodige DOM herbouw kunnen nog steeds traag zijn. Hergebruik templates, vermijd herhaalde volledige rendering en meet echte prestaties.
Voor een grote applicatie die al is gebouwd rond een framework's state management en routing, kan het gebruik van de eigen componenten van dat framework simpeler zijn. Web Components presteren goed wanneer een stabiele UI element een framework of CMS grens moet oversteken.
14. Probleemoplossing
| Symptoom | Waarschijnlijke oorzaak | Wat te controleren |
|---|---|---|
| Kaart is leeg | Module is niet geladen | DevTools console, URL, server MIME type |
customElements.define geeft een fout |
Ongeldige of duplicaat naam | Koppelteken vereiste en registratie guard |
| CSS wordt niet toegepast binnen de kaart | Shadow DOM boundary | Gebruik custom properties, :host, of ::part |
| Inhoud verschijnt op de verkeerde plek | Slot naam mismatch | Vergelijk slot="title" met <slot name="title"> |
| Klikken op dismiss doet niets | Template knop ontbreekt | Inspect shadow tree en console |
| Component faalt wanneer verplaatst | Initialisatie wordt tweemaal uitgevoerd | Guard shadow root creation |
| Link leidt naar 404 | Voorbeeld URL is niet vervangen | Gebruik een bestaande bestemming |
Onthoud dat connectedCallback() meer dan een keer kan draaien. De guard in onze definitieve voorbeeld houdt de initialisatie één keer; meer geavanceerde componenten kunnen tijdens hun connectiviteits cyclus externe observers of globale event listeners moeten bijvoegen en verwijderen.
15. Wanneer moet je Web Components gebruiken?
Kies ze wanneer een component een herbruikbare, gedocumenteerde HTML interface nodig heeft over verschillende websites, frameworks of CMS omgevingen. Kaarten, notifications, product widgets en kleine interactieve tools zijn goede kandidaten.
Sla de abstractie over wanneer een paar regels gewone HTML en CSS het probleem al oplossen. En heronacht geen native controls zonder een sterke reden.
Een nuttige test: zou een andere applicatie ervan profiteren om dit element te gebruiken zonder te weten hoe het is geïmplementeerd? Ja, dan is een Web Component de moeite waard om te overwegen.
Conclusie
Je hebt een echt herbruikbaar component gebouwd, niet alleen een browser API gelezen. Het heeft een custom tag, scoped styling, configureerbare inhoud, een featured variant en een event dat andere code kan luisteren.
Start met één component dat herhaaldelijk in je projecten voorkomt. Geef het een kleine publieke API, test het in meer dan één layout en houd de afhankelijkheden minimaal.
De lange termijn waarde van Web Components is niet dat ze elke framework vervangen. Het is dat ze nuttige interface elementen laten outlive de framework of CMS die ze eerst hostte.