Web Components
Web Components is a suite of different technologies allowing you to create reusable custom elements — with their functionality encapsulated away from the rest of your code — and utilize them in your web apps.
Concepts and usage
As developers, we all know that reusing code as much as possible is a good idea. This has traditionally not been so easy for custom markup structures — think of the complex HTML (and associated style and script) you've sometimes had to write to render custom UI controls, and how using them multiple times can turn your page into a mess if you are not careful.
Web Components aims to solve such problems — it consists of three main technologies, which can be used together to create versatile custom elements with encapsulated functionality that can be reused wherever you like without fear of code collisions.
The basic approach for implementing a web component generally looks something like this:
  1. Create a class in which you specify your web component functionality, using the ECMAScript 2015 class syntax (see Classes for more information). 
  2. Register your new custom element using the CustomElementRegistry.define() method, passing it the element name to be defined, the class or function in which its functionality is specified, and optionally, what element it inherits from.
  3. If required, attach a shadow DOM to the custom element using Element.attachShadow() method. Add child elements, event listeners, etc., to the shadow DOM using regular DOM methods.
  4. If required, define an HTML template using <template> and <slot>. Again use regular DOM methods to clone the template and attach it to your shadow DOM.
  5. Use your custom element wherever you like on your page, just like you would any regular HTML element.
Tutorials
Using custom elements
A guide showing how to use the features of custom elements to create simple web components, as well as looking into lifecycle callbacks and some other more advanced features.
Using shadow DOM
A guide that looks at shadow DOM fundamentals, showing how to attach a shadow DOM to an element, add to the shadow DOM tree, style it, and more.
Using templates and slots
A guide showing how to define a reusable HTML structure using <template> and <slot> elements, and then use that structure inside your web components.
Reference
Custom elements
CustomElementRegistry
Contains functionality related to custom elements, most notably the CustomElementRegistry.define() method used to register new custom elements so they can then be used in your document.
Window.customElements
Returns a reference to the CustomElementRegistry object.
Life cycle callbacks
Special callback functions defined inside the custom element's class definition, which affect its behavior:
Extensions for creating custom built-in elements
CSS pseudo-classes
Pseudo-classes relating specifically to custom elements:
CSS pseudo-elements
Pseudo-elements relating specifically to custom elements:
::part: Represents any element within a shadow tree that has a matching part attribute.
Shadow DOM
ShadowRoot
Represents the root node of a shadow DOM subtree.
Element extensions
Extensions to the Element interface related to shadow DOM:
Relevant Node additions
Additions to the Node interface relevant to shadow DOM:
Event extensions
Extensions to the Event interface related to shadow DOM:
HTML templates
<template>
Contains an HTML fragment that is not rendered when a containing document is initially loaded, but can be displayed at runtime using JavaScript, mainly used as the basis of custom element structures. The associated DOM interface is HTMLTemplateElement​.
<slot>
A placeholder inside a web component that you can fill with your own markup, which lets you create separate DOM trees and present them together. The associated DOM interface is HTMLSlotElement.
The slot global HTML attribute
Assigns a slot in a shadow DOM shadow tree to an element.
Element.assignedSlot
A read-only attribute which returns a reference to the <slot> in which this element is inserted.
Text.assignedSlot
A read-only attribute which returns a reference to the <slot> in which this text node is inserted.
Element extensions
Extensions to the Element interface related to slots:
Element.slot: Returns the name of the shadow DOM slot attached to the element.
CSS pseudo-elements
Pseudo-elements relating specifically to slots:
::slotted: Matches any content that is inserted into a slot.
The slotchange event
Fired on an HTMLSlotElement instance (<slot> element) when the node(s) contained in that slot change.
Examples
We are building up a number of examples in our web-components-examples GitHub repo. More will be added as time goes on.
Specifications
The template element and custom elements
Specification
HTML Standard (HTML)
# the-template-element
The shadow DOM
Specification
DOM Standard (DOM)
# interface-shadowroot
Browser compatibility
In general:
For detailed browser support of specific features, you'll have to consult the reference pages listed above.
See also
Found a problem with this page?
Last modified: Jun 28, 2021, by MDN contributors
Change your language
Related Topics
Guides
Using custom elements
Using shadow DOM
Using templates and slots
Interfaces
CustomElementRegistry
HTMLSlotElement
HTMLTemplateElement
ShadowRoot
DocumentOrShadowRoot
Slotable
Properties
Element.shadowRoot
Element.slot
Event.composed
Event.composedPath
Node.isConnected
Window.customElements
Methods
Document.createElement()
Element.attachShadow()
Node.getRootNode()
Web Technologies
Learn Web Development
About MDN
Feedback
About
MDN Web Docs Store
Contact Us
Firefox
MDN
Mozilla

© 2005-2021 Mozilla and individual contributors. Content is available under these licenses.
Terms
Privacy
Cookies
Web technology for developersWeb Components