Web Components : Créez des composants UI réutilisables avec JavaScript pur
Apprenez les Web Components étape par étape en créant une carte UI réutilisable avec Custom Elements, Shadow DOM, HTML Templates, slots et modules JavaScript. Aucun framework ou outil de build requis.
Web Components : Construire des composants UI réutilisables avec du JavaScript pur
Imaginez créer une carte pour votre site web, puis l'utiliser dans un thème WordPress, une extension Joomla ou une application autonome sans la réécrire pour chaque environnement.
C'est la promesse des Web Components : des outils natifs du navigateur pour construire des éléments HTML réutilisables. Aucun React, Vue, paquet npm ou bundler n'est requis pour l'exemple que nous allons construire.
À la fin de ce tutoriel, vous aurez un composant <ui-card> fonctionnel avec un contenu personnalisable, des styles isolés, une variante mise en avant, un bouton de fermeture et un événement public. Nous le construirons par petites étapes pour que vous puissiez voir ce que chaque technologie apporte.
Ce que vous allez construire
Notre composant final prendra en charge ce 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>
Aperçu visuel — cartes standard et mise en avant
<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">Carte standard</strong> <span>Cette carte utilise l'apparence par défaut.</span> </div> <div style="padding:20px;border:1px solid #93c5fd;border-radius:12px;background:#eff6ff"> <strong style="display:block;color:#1d4ed8;margin-bottom:6px">Carte mise en avant</strong> <span>Cette carte a une apparence mise en évidence.</span> </div> </div>
Cet aperçu est la cible de conception, pas une capture d'écran d'une bibliothèque sans rapport. Nous le reproduirons en utilisant le code ci-dessous.
1. Comprendre les quatre briques de base
Les Custom Elements nous permettent d'enregistrer une nouvelle balise HTML et son comportement JavaScript. Le Shadow DOM donne à l'élément son propre DOM interne et des styles étendus. Les templates HTML et slots permettent de réutiliser la structure tout en insérant un contenu différent dans chaque instance. Les modules ES permettent de charger le composant depuis un fichier JavaScript normal.
Ce sont des fonctionnalités distinctes. Un Custom Element n'a pas à utiliser le Shadow DOM, et vous n'avez pas besoin d'un framework pour utiliser l'un d'entre eux.
2. Créer les fichiers du projet
Créez cette structure dans votre éditeur :
web-components-demo/
├── index.html
├── components/
│ └── ui-card.js
└── css/
└── main.css
Mettez ceci dans 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>
Ajoutez les styles au niveau de la page dans 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;
}
Lancez un serveur HTTP local depuis le répertoire du projet, par exemple :
python -m http.server 8000
Visitez http://localhost:8000. Le titre apparaît, mais la carte n'a pas encore de contenu visible. Utilisez un serveur HTTP plutôt que d'ouvrir index.html avec file:// : les règles de chargement des modules du navigateur peuvent bloquer les imports de fichiers locaux.
3. Enregistrer votre premier Custom Element
Créez components/ui-card.js :
class UiCard extends HTMLElement {
connectedCallback() {
this.textContent = 'Hello from a Web Component!';
}
}
customElements.define('ui-card', UiCard);
Rafraîchissez la page. Vous devriez maintenant voir :
Résultat attendu — Étape 3
Bonjour depuis un Web Component !
HTMLElement fournit le comportement DOM normal. connectedCallback() s'exécute quand l'élément se connecte au document. customElements.define() associe la classe à la balise HTML.
Le trait d'union dans ui-card est requis pour les noms de Custom Elements autonomes. Le callback peut s'exécuter à nouveau si l'élément est détaché et réinséré, ce qui importe quand nous ajoutons de la logique d'initialisation.
4. Donner son propre design à la carte avec le Shadow DOM
Remplacez ui-card.js par :
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);
Résultat attendu — Étape 4
Ouvrez les DevTools, inspectez <ui-card>, et développez #shadow-root (open). Vous verrez l'article interne et la feuille de styles.
Contrairement aux sélecteurs de document ordinaires, le CSS global tel que article { border: none } n'atteint normalement pas cet arbre shadow. Les propriétés héritées et les propriétés personnalisées CSS peuvent encore franchir la frontière. Le Shadow DOM encapsule la présentation ; ce n'est pas une sandbox de sécurité.
La garde if (this.shadowRoot) empêche d'attacher une seconde racine shadow si l'élément se reconnecte.

5. Séparer la mise en page avec un template HTML
Tout intégrer dans connectedCallback() devient gênant à mesure qu'un composant grandit. Définissons le balisage une fois et clonons-le pour chaque carte.
Remplacez le fichier par :
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 est un fragment de document. cloneNode(true) copie toute la structure dans l'arbre shadow de chaque carte. Le template lui-même ne s'affiche pas tant qu'on ne le clone et ne l'insère pas.
Cette version ressemble presque à l'identique. L'amélioration est architecturale : un template peut servir de nombreuses instances.
6. Insérer un contenu différent en utilisant les slots
Une carte réutilisable n'est pas utile si chaque instance a le même titre. Remplacez uniquement la déclaration du template en haut de ui-card.js par ce qui suit ; gardez la classe et le code d'enregistrement de l'étape 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>
`;
Remplacez maintenant <ui-card></ui-card> dans 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>
Résultat attendu — Étape 6
Le slot nommé reçoit l'élément marqué slot="title". Le slot sans nom reçoit le paragraphe. Le slot action reçoit le lien. Le texte de secours d'un slot s'affiche si rien ne lui est assigné.
La mise en page vit dans le composant ; les mots et liens réels restent dans le HTML de la page. C'est particulièrement utile pour le contenu CMS. Remplacez /tutorial par une vraie destination dans votre projet.
7. Créer une variante mise en avant avec CSS
À l'intérieur du bloc <style> du template, ajoutez :
:host {
display: block;
}
:host([variant="featured"]) article {
background: #eff6ff;
border-color: #93c5fd;
}
Puis remplacez la carte unique dans index.html par deux cartes :
<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>
Résultat attendu — Étape 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">Carte standard</strong> Cette carte utilise l'apparence par défaut. </div> <div style="padding:18px;border:1px solid #93c5fd;border-radius:12px;background:#eff6ff"> <strong style="display:block;color:#1d4ed8;margin-bottom:6px">Carte mise en avant</strong> Cette carte a une apparence mise en évidence. </div> </div>
C'est une fonctionnalité particulièrement utile de :host() : il stylise le composant en fonction des attributs de l'élément personnalisé. Si JavaScript modifie variant plus tard, le CSS se met à jour automatiquement. Aucun attributeChangedCallback() n'est nécessaire pour un changement purement piloté par CSS.
8. Ajouter un bouton de fermeture et un événement public
Rendons la carte interactive. À l'intérieur du <article> du template, ajoutez ce bouton avant le titre :
<button class="dismiss" type="button" aria-label="Dismiss card">
×
</button>
Ajoutez ces règles au CSS du 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;
}
Remplacez connectedCallback() dans la classe par :
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();
});
}
Dans index.html, ajoutez ce script avant </body> :
<script type="module">
document.addEventListener('card-dismissed', () => {
console.log('A card was dismissed.');
});
</script>
Ouvrez la console du navigateur et cliquez sur ×. La carte disparaît et la console affiche le message.
L'événement fournit un point d'intégration public : l'application environnante n'a pas besoin de connaître le bouton interne de la carte. bubbles fait bouillonner l'événement ; composed permet de franchir une frontière shadow le cas échéant. Ici, l'événement provient de l'élément hôte lui-même.
9. Version finale complète : copier et utiliser

Vous pouvez maintenant remplacer tout le contenu de components/ui-card.js par cette version consolidée. Elle ajoute la personnalisation CSS et les parties exportées tout en conservant le comportement construit dans les étapes précédentes.
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);
}
Contrairement à une démo rapide, cette version n'essaie pas d'attacher la racine shadow deux fois, n'insère pas de contenu non fiable avec innerHTML, et ne dépend pas d'un framework. La chaîne de template est contrôlée par le développeur ; n'interpolez jamais d'entrée utilisateur non fiable dedans.
10. Le styliser depuis le site hôte
Le Shadow DOM n'est pas censé rendre la personnalisation impossible. Il vous encourage à définir une interface de stylisation intentionnelle.
Dans css/main.css, ajoutez :
ui-card {
--card-border: #cbd5e1;
--card-title-color: #0f766e;
}
ui-card::part(container) {
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}
Les propriétés personnalisées sont héritées par l'arbre shadow et contrôlent les valeurs que nous avons exposées. L'attribut part="container" permet au CSS externe de cibler un élément interne sélectionné avec ::part(container).
Si vous avez besoin d'un fond mis en avant différent, utilisez --card-featured-background. C'est préférable à forcer les consommateurs à dépendre de la structure DOM interne exacte.
11. Réutiliser la carte dans WordPress, Joomla ou du HTML pur
Copiez ui-card.js dans le site cible et chargez-le comme un module JavaScript :
<script type="module" src="/assets/js/ui-card.js"></script>
Puis utilisez <ui-card> dans le balisage de la page. Dans WordPress, enregistrez les assets via les APIs de chargement de scripts supportées par le thème ou le plugin, en utilisant le support de module approprié à votre version de WordPress. Dans Joomla, utilisez le gestionnaire d'assets web pour enregistrer et charger le module. Ne dispersez pas de balises script codées en dur dans les templates de production.
Pour une carte générée par un CMS, rendez le titre, le paragraphe et le lien comme du HTML slotted. Échappez le contenu et les attributs selon les règles de sortie du CMS.
Avantage pratique : un module Joomla et un bloc WordPress peuvent tous deux sortir la même balise personnalisée tout en partageant une implémentation de composant unique. Chaque CMS reste responsable de la récupération et de l'échappement de son propre contenu.
12. Accessibilité, SEO et amélioration progressive
Utilisez des contrôles HTML natifs à l'intérieur des composants autant que possible. Notre action de fermeture utilise un vrai button, qui fournit la sémantique d'activation au clavier, et un aria-label car × seul n'est pas descriptif.
Si un utilisateur ferme une carte avec le focus clavier, considérez où le focus devrait aller ensuite dans une interface plus complexe. Les dialogues, menus et comboboxes ont besoin de beaucoup plus de comportement d'accessibilité que cet exemple.
Gardez le contenu important dans un balisage light-DOM significatif quand c'est pratique. Si JavaScript échoue, le navigateur ne mettra pas à niveau <ui-card> ; le titre et le paragraphe slotted restent dans le document, bien que l'enveloppe stylisée et le bouton de fermeture du composant n'existent pas.
Pour les moteurs de recherche, n'assumez pas que le contenu JavaScript-seul est indexé identiquement dans chaque robot. Le contenu critique devrait être disponible dans le HTML initial ou via une stratégie de rendu appropriée.
Le Shadow DOM a aussi des limitations : les sélecteurs CSS de document ordinaires ne stylisent pas les nœuds internes, et certaines relations ARIA ID ne peuvent pas franchir les frontières shadow. Concevez les APIs de composant avec ces contraintes à l'esprit.
13. Les Web Components sont-ils toujours plus rapides ?
Pas nécessairement. Les Web Components évitent d'exiger un runtime de framework particulier, mais la performance dépend de la quantité de JavaScript, de la complexité du DOM, de la fréquence de rendu et de l'architecture de l'application.
Une petite carte est un bon candidat. Des centaines d'éléments complexes avec une reconstruction DOM inutile peuvent encore être lents. Réutilisez les templates, évitez le rendu complet répété, et mesurez la performance réelle.
Pour une grande application déjà construite autour de la gestion d'état et du routage d'un framework, utiliser les propres composants de ce framework peut être plus simple. Les Web Components brillent quand un élément UI stable doit franchir des frontières de framework ou de CMS.
14. Dépannage
| Symptôme | Cause probable | Ce qu'il faut vérifier |
|---|---|---|
| Carte vide | Module non chargé | Console DevTools, URL, type MIME du serveur |
customElements.define lance une erreur |
Nom invalide ou en double | Exigence du trait d'union et garde d'enregistrement |
| CSS ne s'applique pas dans la carte | Frontière Shadow DOM | Utilisez les propriétés personnalisées, :host, ou ::part |
| Contenu au mauvais endroit | Nom de slot qui ne correspond pas | Comparez slot="title" avec <slot name="title"> |
| Clic sur fermer ne fait rien | Bouton du template manquant | Inspectez l'arbre shadow et la console |
| Composant échoue quand déplacé | L'initialisation s'exécute deux fois | Gardez la création de racine shadow |
| Lien mène à 404 | URL d'exemple non remplacée | Utilisez une destination existante |
Rappelez-vous que connectedCallback() peut s'exécuter plus d'une fois. La garde dans notre exemple final garde l'initialisation unique ; des composants plus sophistiqués peuvent avoir besoin d'attacher et de supprimer des observateurs externes ou des écouteurs d'événements globaux pendant leur cycle de vie de connexion.
15. Quand utiliser les Web Components ?
Choisissez-les quand un composant a besoin d'une interface HTML réutilisable et documentée à travers plusieurs sites web, frameworks ou environnements CMS. Cartes, notifications, widgets produits et petits outils interactifs sont de bons candidats.
Évitez l'abstraction quand quelques lignes de HTML et CSS ordinaires résolvent déjà le problème. Et ne recréez pas les contrôles natifs sans raison forte.
Un test utile : une autre application bénéficierait-elle d'utiliser cet élément sans savoir comment il a été implémenté ? Si oui, un Web Component mérite d'être considéré.
Conclusion
Vous avez construit un vrai composant réutilisable, pas seulement lu sur une API de navigateur. Il a une balise personnalisée, un stylisation étendue, un contenu configurable, une variante mise en avant et un événement que d'autres codes peuvent écouter.
Commencez par un composant qui apparaît répétitivement dans vos projets. Donnez-lui une petite API publique, testez-le dans plus d'une mise en page, et gardez ses dépendances minimales.
La valeur à long terme des Web Components n'est pas qu'ils remplacent chaque framework. C'est qu'ils laissent les éléments d'interface utiles survivre au framework ou au CMS qui les a hébergés en premier.