Web Components: Crea componenti UI riutilizzabili con Vanilla JavaScript
Impara i Web Components passo dopo passo costruendo una scheda UI riutilizzabile con Custom Elements, Shadow DOM, HTML Templates, slots e moduli JavaScript. Nessun framework o strumenti di build richiesti.
Web Components: Creare componenti UI riutilizzabili con Vanilla JavaScript
Immagina di creare una card per il tuo sito web e poi di usarla in un tema WordPress, un'estensione Joomla o un'applicazione autonoma senza riscriverla per ogni ambiente.
Questa è la promessa dei Web Components: strumenti nativi del browser per creare elementi HTML riutilizzabili. Non sono necessari React, Vue, pacchetti npm o bundler per l'esempio che realizzeremo.
Al termine di questo tutorial, avrai un componente <ui-card> funzionante con contenuto personalizzabile, stili isolati, una variante in evidenza, un pulsante di chiusura e un evento pubblico. Lo costruiremo a piccoli passi così potrai vedere cosa contribuisce ogni tecnologia.
Cosa costruirai
Il componente finito supporterà questo 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>
Anteprima visiva — card standard e in evidenza
<div style="padding:16px;border:1px solid #dce3ec;border-radius:14px;background:#f8fafc;margin:16px 0"> <div style="padding:20px;border:1px solid #dce3ec;border-radius:12px;background:#fff;margin-bottom:12px"> <strong style="display:block;margin-bottom:6px">Standard card</strong> <span>This card uses the default appearance.</span> </div> <div style="padding:20px;border:1px solid #93c5fd;border-radius:12px;background:#eff6ff"> <strong style="display:block;color:#1d4ed8;margin-bottom:6px">Featured card</strong> <span>This card has a highlighted appearance.</span> </div> </div>
Questa anteprima è l'obiettivo di progettazione, non uno screenshot di una libreria non correlata. La riprodurremo usando il codice seguente.
1. Comprendere i quattro mattoni costitutivi
Custom Elements ci consentono di registrare un nuovo tag HTML e il suo comportamento JavaScript. Shadow DOM conferisce all'elemento il proprio DOM interno e stili con ambito. HTML template e slot ci consentono di riutilizzare la struttura inserendo contenuti diversi in ogni istanza. ES Modules ci consentono di caricare il componente da un normale file JavaScript.
Sono funzionalità separate. Un Custom Element non deve necessariamente usare Shadow DOM, e non hai bisogno di un framework per usare nessuna di esse.
2. Creare i file del progetto
Crea questa struttura nel tuo editor:
web-components-demo/
├── index.html
├── components/
│ └── ui-card.js
└── css/
└── main.css
Metti questo 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>
Aggiungi gli stili a livello di pagina a 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;
}
Esegui un server HTTP locale dalla directory del progetto, ad esempio:
python -m http.server 8000
Visita http://localhost:8000. L'intestazione appare, ma la card non ha ancora contenuto visibile. Usa un server HTTP invece di aprire index.html con file://: le regole di caricamento dei moduli del browser possono bloccare le importazioni da file locali.
3. Registrare il tuo primo Custom Element
Crea components/ui-card.js:
class UiCard extends HTMLElement {
connectedCallback() {
this.textContent = 'Hello from a Web Component!';
}
}
customElements.define('ui-card', UiCard);
Aggiorna la pagina. Dovresti ora vedere:
Risultato previsto — Passaggio 3
Hello from a Web Component!
HTMLElement fornisce il comportamento DOM normale. connectedCallback() viene eseguito quando l'elemento si connette al documento. customElements.define() associa la classe al tag HTML.
Il trattino in ui-card è richiesto per i nomi degli elementi autonomi Custom Element. Il callback può essere eseguito di nuovo se l'elemento viene scollegato e reinserito, cosa che importa quando aggiungiamo la logica di inizializzazione.
4. Dare alla card il proprio design con Shadow DOM
Sostituisci ui-card.js con:
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);
Risultato previsto — Passaggio 4
<div style="padding:22px;border:1px solid #dce3ec;border-radius:12px;background:#fff;margin:16px 0"> <strong style="display:block;color:#2563eb;font-size:20px;margin-bottom:10px">My reusable card</strong> This content lives inside Shadow DOM. </div>
Apri DevTools, ispeziona <ui-card> ed espandi #shadow-root (open). Vedrai l'articolo interno e il foglio di stile.
A differenza dei selettori del documento ordinari, il CSS globale come article { border: none } non raggiunge normalmente questo albero shadow. Le proprietà ereditate e le proprietà CSS personalizzate possono comunque attraversare il confine. Shadow DOM incapsula la presentazione; non è un sandbox di sicurezza.
La protezione if (this.shadowRoot) impedisce di collegare un secondo shadow root se l'elemento si riconnette.

5. Separare il layout con un template HTML
Inserire tutto dentro connectedCallback() diventa scomodo man mano che il componente cresce. Definiamo il markup una volta e cloniamolo per ogni card.
Sostituisci il file con:
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 è un frammento di documento. cloneNode(true) copia l'intera struttura nell'albero shadow di ogni card. Il template stesso non viene renderizzato finché non lo cloniamo e lo inseriamo.
Questa versione sembra quasi identica. Il miglioramento è architettonico: un singolo template può servire molte istanze.
6. Inserire contenuti diversi usando gli slot
Una card riutilizzabile non è utile se ogni istanza ha lo stesso titolo. Sostituisci solo la dichiarazione del template all'inizio di ui-card.js con quanto segue; mantieni la classe e il codice di registrazione del passaggio 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>
`;
Ora sostituisci <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>
Risultato previsto — Passaggio 6
<div style="padding:22px;border:1px solid #dce3ec;border-radius:12px;background:#fff;margin:16px 0"> <strong style="display:block;color:#2563eb;font-size:20px;margin-bottom:10px">Learn Web Components</strong> <p style="margin:0 0 12px">Build reusable interfaces with native JavaScript.</p> <span style="color:#2563eb;font-weight:600">Read the tutorial</span> </div>
Lo slot named riceve l'elemento contrassegnato da slot="title". Lo slot unnamed riceve il paragrafo. Lo slot action riceve il link. Il testo di fallback di uno slot appare se non gli è assegnato nulla.
Il layout vive nel componente; le parole e i link effettivi rimangono nell'HTML della pagina. Questo è particolarmente utile per i contenuti CMS. Sostituisci /tutorial con una destinazione reale nel tuo progetto.
7. Creare una variante featured con CSS
All'interno del blocco <style> del template, aggiungi:
:host {
display: block;
}
:host([variant="featured"]) article {
background: #eff6ff;
border-color: #93c5fd;
}
Poi sostituisci la singola card in index.html con due card:
<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>
Risultato previsto — Passaggio 7
<div style="padding:12px;border:1px solid #e2e8f0;border-radius:14px;background:#fafafa;margin:16px 0"> <div style="padding:18px;border:1px solid #dce3ec;border-radius:12px;background:white;margin-bottom:12px"> <strong style="display:block;margin-bottom:6px">Standard card</strong> This card uses the default appearance. </div> <div style="padding:18px;border:1px solid #93c5fd;border-radius:12px;background:#eff6ff"> <strong style="display:block;color:#1d4ed8;margin-bottom:6px">Featured card</strong> This card has a highlighted appearance. </div> </div>
Questa è una funzionalità particolarmente utile di :host(): consente di stilizzare il componente in base agli attributi dell'elemento personalizzato. Se JavaScript modifica variant in seguito, il CSS si aggiorna automaticamente. Non è necessario attributeChangedCallback() per una modifica guidata esclusivamente da CSS.
8. Aggiungere un pulsante di chiusura e un evento pubblico
Rendiamo la card interattiva. All'interno del blocco <article> del template, aggiungi questo pulsante prima del titolo:
<button class="dismiss" type="button" aria-label="Dismiss card">
×
</button>
Aggiungi queste regole al CSS del 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;
}
Sostituisci connectedCallback() nella classe con:
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, aggiungi questo script prima di </body>:
<script type="module">
document.addEventListener('card-dismissed', () => {
console.log('A card was dismissed.');
});
</script>
Apri la console del browser e clicca su ×. La card scompare e nella console viene visualizzato il messaggio.
L'evento fornisce un punto di integrazione pubblico: l'applicazione circostante non ha bisogno di sapere nulla sul pulsante interno della card. bubbles rende l'evento bubbles; composed consente di attraversare un confine shadow quando applicabile. Qui l'evento ha origine sull'elemento host stesso.
9. Versione finale completa: copia e usa

Ora puoi sostituire l'intero contenuto di components/ui-card.js con questa versione consolidata. Aggiunge personalizzazione CSS ed esportazione di parti, mantenendo il comportamento costruito nei passaggi precedenti.
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);
}
A differenza di una demo rapida, questa versione non tenta di collegare lo shadow root due volte, non inserisce contenuto non attendibile con innerHTML e non si affida a un framework. La stringa del template è controllata dallo sviluppatore; non interpolare mai input utente non attendibili in essa.
10. Stilizzarlo dal sito di hosting
Shadow DOM non è pensato per rendere impossibile la personalizzazione. Ti incoraggia a definire un'interfaccia di stile intenzionale.
In css/main.css, aggiungi:
ui-card {
--card-border: #cbd5e1;
--card-title-color: #0f766e;
}
ui-card::part(container) {
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}
Le proprietà CSS personalizzate vengono ereditate dall'albero shadow e controllano i valori che abbiamo esposto. L'attributo part="container" consente al CSS esterno di prendere di mira un elemento interno selezionato con ::part(container).
Se desideri uno sfondo featured diverso, usa --card-featured-background. È preferibile a costringere i consumatori a dipendere dalla struttura DOM interna esatta.
11. Riutilizzare la card in WordPress, Joomla o HTML semplice
Copia ui-card.js nel sito di destinazione e caricalo come modulo JavaScript:
<script type="module" src="/assets/js/ui-card.js"></script>
Poi usa <ui-card> nel markup della pagina. In WordPress, registra gli asset tramite le API di caricamento script supportate dal tema o plugin, utilizzando il supporto per i moduli appropriato alla tua versione di WordPress. In Joomla, usa il Web Asset Manager per registrare e caricare il modulo. Non spargere tag script hardcoded nei template di produzione.
Per una card generata da CMS, renderizza il titolo, il paragrafo e il link come HTML negli slot. Esegui l'escape di contenuti e attributi secondo le regole di output del CMS.
Vantaggio pratico: un modulo Joomla e un blocco WordPress possono entrambi emettere lo stesso tag personalizzato condividendo un'unica implementazione del componente. Ogni CMS rimane responsabile del recupero e dell'escape del proprio contenuto.
12. Accessibilità, SEO e progressive enhancement
Usa controlli HTML nativi all'interno dei componenti quando possibile. La nostra azione di chiusura usa un vero button, che fornisce semantica di attivazione da tastiera, e un aria-label perché × da solo non è descrittivo.
Se un utente chiude una card con il focus da tastiera, considera dove dovrebbe andare il focus successivo in un'interfaccia più complessa. Dialog, menu e combobox richiedono molto più comportamento di accessibilità rispetto a questo esempio.
Mantieni i contenuti importanti in markup light-DOM significativo quando praticabile. Se JavaScript fallisce, il browser non aggiornerà <ui-card>; il titolo e il paragrafo in slot rimangono nel documento, anche se il guscio stilizzato del componente e il pulsante di chiusura non esisteranno.
Per i motori di ricerca, non presumere che i contenuti solo JavaScript siano indicizzati in modo identico da ogni crawler. I contenuti critici dovrebbero essere disponibili nell'HTML iniziale o tramite una strategia di rendering appropriata.
Shadow DOM presenta anche limitazioni: i selettori CSS del documento ordinario non stilizzano i nodi interni, e alcune relazioni ID ARIA non possono attraversare i confini shadow. Progetta le API dei componenti tenendo conto di questi vincoli.
13. I Web Components sono sempre più veloci?
Non necessariamente. I Web Components evitano di richiedere un particolare runtime di framework, ma le prestazioni dipendono dalla quantità di JavaScript, dalla complessità del DOM, dalla frequenza di rendering e dall'architettura dell'applicazione.
Una card piccola è un buon candidato. Centinaia di elementi complessi con ricostruzione DOM non necessaria potrebbero comunque essere lenti. Riutilizza i template, evita rendering completi ripetuti e misura le prestazioni reali.
Per un'applicazione grande già costruita attorno alla gestione dello stato e al routing di un framework, usare i componenti propri di quel framework potrebbe essere più semplice. I Web Components brillano quando un elemento UI stabile deve attraversare confini di framework o CMS.
14. Risoluzione dei problemi
| Sintomo | Causa probabile | Cosa controllare |
|---|---|---|
| Card vuota | Il modulo non si è caricato | Console DevTools, URL, tipo MIME del server |
customElements.define genera un'eccezione |
Nome non valido o duplicato | Requisito del trattino e protezione di registrazione |
| Il CSS non si applica all'interno della card | Confine Shadow DOM | Usa proprietà personalizzate, :host o ::part |
| Il contenuto appare nel posto sbagliato | Discrepanza nome slot | Confronta slot="title" con <slot name="title"> |
| Cliccare su chiudi non funziona | Pulsante del template mancante | Ispeziona l'albero shadow e la console |
| Il componente fallisce quando spostato | L'inizializzazione viene eseguita due volte | Proteggi la creazione dello shadow root |
| Il link porta a 404 | L'URL di esempio non è stato sostituito | Usa una destinazione esistente |
Ricorda che connectedCallback() può essere eseguito più di una volta. La protezione nel nostro esempio finale mantiene l'inizializzazione una tantum; componenti più sofisticati potrebbero dover collegare e rimuovere osservatori esterni o listener di eventi globali durante il loro ciclo di vita di connessione.
15. Quando usare i Web Components?
Sceglili quando un componente ha bisogno di un'interfaccia HTML riutilizzabile e documentata in diversi siti web, framework o ambienti CMS. Card, notifiche, widget di prodotti e piccoli strumenti interattivi sono buoni candidati.
Salta l'astrazione quando poche righe di HTML e CSS ordinari risolvono già il problema. E non ricreare controlli nativi senza una valida ragione.
Un test utile: un'altra applicazione trarrebbe vantaggio dall'usare questo elemento senza sapere come è stato implementato? Se sì, un Web Component merita di essere considerato.
Conclusione
Hai costruito un componente riutilizzabile reale, non solo letto su un'API del browser. Ha un tag personalizzato, stile con ambito, contenuto configurabile, una variante featured e un evento a cui altro codice può ascoltare.
Inizia con un componente che appare ripetutamente nei tuoi progetti. Dagli una piccola API pubblica, testalo in più di un layout e mantieni le sue dipendenze minime.
Il valore a lungo termine dei Web Components non è che sostituiscano ogni framework. È che consentono a elementi di interfaccia utili di sopravvivere al framework o CMS che li ha ospitati per primi.