Web Components the Right Way

A curated list of awesome Web Components resources.

Web Components — 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.

Contents

• Introduction
• Standards
  • Custom Elements
  • Shadow DOM
  • HTML Templates
  • CSS Shadow Parts
• Polyfills
  • Custom Elements polyfills
  • Customized Built-in Elements polyfills
  • Shadow DOM shims
  • HTML Templates polyfills
• Guides
  • Accessibility
  • Best Practices
  • Codelabs
  • Examples
• Articles
  • Architecture
  • Interoperability
  • Limitations
  • Styling
• Real World
  • Case Studies
  • Components
  • Component Libraries
  • Design Systems
  • Use Cases
• Libraries
  • Class Based
  • Functional
  • Integrations
  • Benchmarks
• Frameworks
  • Angular
  • React
  • Vue
  • Svelte
• Ecosystem
  • Starter Kits
  • Tools
• Books
• Tutorials
• Insights
  • Podcasts
  • Presentations
  • Talks
• Usage Metrics
• Proposals
  • Form-associated Custom Elements
  • Constructable Stylesheet Objects
  • Custom State Pseudo Class
• Miscellaneous
• History
• Who to follow
• License

Web Components the Right Way was made with love by Mateus Ortiz and maintained by Serhii Kulykov

Introduction

• Web Components 101
• Intro to Web Components
• MDN - Web Components
• The Holy Grail Of Reusable Components: Custom Elements, Shadow DOM, And NPM
• The Power of Web Components

Standards

Custom Elements

Custom Elements provide a way for authors to build their own fully-featured DOM elements.

• HTML Living Standard: Custom elements
• A Guide to Custom Elements for React Developers
• All about HTML Custom Elements
• Custom Elements v1: Reusable Web Components
• Handy Custom Elements’ Patterns
• MDN - Using Custom Elements
• web-platform-tests

Shadow DOM

Shadow DOM describes a method of combining multiple DOM trees into one hierarchy and how these trees interact with each other within a document, thus enabling better composition of the DOM.

• DOM Living Standard: Interface ShadowRoot
• DOM Living Standard: Shadow tree
• MDN - Using Shadow DOM
• Open vs. Closed Shadow DOM
• Shadow DOM in depth
• Shadow DOM v1: Self-Contained Web Components
• The Rise of Shadow DOM
• Understanding Slot Updates with Web Components
• What is the Shadow DOM?
• web-platform-tests

HTML Templates

<template> element is used to declare fragments of HTML that can be cloned and inserted in the document by script.

• HTML Living Standard: The template element
• MDN - <template>: The Content Template element
• MDN - Using templates and slots
• web-platform-tests

CSS Shadow Parts

CSS Shadow Parts allow developers to expose certain elements inside Shadow DOM for styling purposes.

• W3C First Public Working Draft
• CSS Shadow Parts are coming!
• MDN - ::part() CSS pseudo element
• MDN - part global attribute
• ::part and ::theme, an ::explainer
• web-platform-tests

Polyfills

Custom Elements polyfills

• [@webcomponents/custom-elements](https://github.com/webcomponents/polyfills/tree/master/packages/custom-elements) - Custom Elements polyfill by Polymer team.
• document-register-element - Custom Elements polyfill by Andrea Giammarchi.

Customized Built-in Elements polyfills

• [@corpuscule/custom-builtin-elements](https://github.com/corpusculejs/custom-builtin-elements) - Customized built-in elements polyfill by CorpusculeJS.
• [@ungap/custom-elements-builtin](https://github.com/ungap/custom-elements-builtin) - Customized built-in elements polyfill by ungap project.

Shadow DOM shims

• [@webcomponents/shadydom](https://github.com/webcomponents/polyfills/tree/master/packages/shadydom) - ShadowDOM v1 shim.
• [@webcomponents/shadycss](https://github.com/webcomponents/polyfills/tree/master/packages/shadycss) - ShadowDOM style encapsulation shim.
• [@lwc/synthetic-shadow](https://github.com/salesforce/lwc/blob/master/packages/@lwc/synthetic-shadow) - Shadow DOM polyfill by LWC.

HTML Templates polyfills

• [@webcomponents/template](https://github.com/webcomponents/polyfills/tree/master/packages/template) - Minimal polyfill for <template>.
• [@ungap/import-node](https://github.com/ungap/import-node) - An importNode polyfill for IE11 by ungap project.

Guides

Accessibility

• Accessibility for Web Components
• How to Make Accessible Web Components — a Brief Guide
• The future of accessibility for custom elements
• The Guide to Accessible Web Components
• Web Components and the Accessibility Object model (AOM)
• Web Components punch list
• Web components still need to be accessible

Best Practices

• Custom Element Best Practices
• Developing Components: Publishing
• Gold Standard Checklist for Web Components
• Guidelines for creating web platform compatible components
• How to Publish Web Components to NPM
• Open Web Components Recommendations

Codelabs

• Build a Story Web Component with LitElement
• Building Custom Elements with Web Components for the 2020 Elections
• Building Web Components with Vanilla JavaScript
• Creating a Reusable Avatar Web Component
• Creating Web Components with Stencil
• From Web Component to Lit Element
• Getting started with LitElement and TypeScript
• Handling data with Web Components
• How to use D3js with WebComponents
• Introduction to Storybook for Web Components
• Navigation Lifecycle using Vaadin Router, LitElement and TypeScript
• Open Web Components: Codelabs
• Recreating The Arduino Pushbutton Using SVG And <lit-element>
• Routing Management with LitElement and TypeScript
• Snake-Eating Game Making with Web Components of Omi and MVP Architecture
• Storybook for web components on steroids
• Testing Workflow for Web Components
• Web Components Tools: A Comparison

Examples

• generic-components - Collection of generic web components with a focus on accessibility, and ease of use.
• howto-components - Collection of web components that implement common web UI patterns.
• open-wc code examples - Collection of best practices and design patterns for developing web components.
• vanilla-retro-js - Vanilla JS UI component library of HTML deprecated tags.
• web-components-examples - Series of web components examples, related to the MDN web components documentation.

Articles

Architecture

• A deep analysis into isomorphic, autonomous cross-framework usage #MicroFrontends
• Frankenstein Migration: Framework-Agnostic Approach (Part 1)
• Frankenstein Migration: Framework-Agnostic Approach (Part 2)
• Generating Config driven Dynamic Forms using Web Components
• Hiding internal framework methods and properties from web component APIs
• How to deliver Custom Elements
• Making Web Components for Different Contexts
• Supporting both automatic and manual registration of custom elements
• Web Components — the right way

Interoperability

• Custom Elements Everywhere
• Custom Elements That Work Anywhere
• JavaScript frameworks, meet Web Components
• Web Components aren’t a framework replacement - they’re better than that
• Web Components: Seamlessly interoperable

Limitations

• Beyond the polyfills: how Web Components affect us today?
• Custom elements, shadow DOM and implicit form submission
• Form-associated custom elements
• You might not need shadow DOM

Styling

• Options for styling web components
• Styling a Web Component
• Styling in the Shadow DOM With CSS Shadow Parts
• Styling is critical to web component reuse, but may prove difficult in practice
• Thinking Through Styling Options for Web Components
• Web Standards Meet User-Land: Using CSS-in-JS to Style Custom Elements

Real World

Case Studies

• Apple Just Shipped Web Components to Production and You Probably Missed It
• Bringing Order to Web Design Chaos (with Web Components)
• Get moving with Microsoft’s FAST web components
• How Web Components Are Used at GitHub and Salesforce
• How we use Web Components at GitHub
• Implementing a Design Language System with Stencil.js
• ING ❤ Web Components
• ING Open-Sources Lion, Its White-Label Web Component Library – Q&A with Thomas Allmer
• Lessons Learned, making our app with Web Components
• Looking back on five years of web components
• Shipping Web Components in 2020
• The Firefox UI is now built with Web Components
• Using web components to encapsulate CSS and resolve design system conflicts
• Web Components at GitHub - Web Components SF Meetup
• Web Components at Scale at Salesforce: Challenges Encountered, Lessons Learnt
• Web Development At Scale: Composable Applications With Web Components
• web.dev engineering blog #1: How we build the site and use Web Components

Components

• <api-viewer> - API documentation and live playground for Web Components.
• <chess-board> - Standalone chess board web component.
• <css-doodle> - Web component for drawing patterns with CSS.
• <dark-mode-toggle> - Custom element that allows to create a dark mode toggle or switch.
• <emoji-picker> - Lightweight emoji picker, distributed as a web component.
• <fg-modal> - Accessible modal dialog web component.
• <file-viewer> - Web component built with Svelte to view files.
• <json-viewer> - Web component to visualize JSON data in a tree view.
• <lite-youtube> - Lite YouTube embed with a focus on visual performance.
• <midi-player> - MIDI file player and visualizer web components.
• <model-viewer> - Web component for rendering interactive 3D models.
• <player-x> - Media player web component.
• <progressive-image> - Custom element to progressively enhance image placeholders.
• <range-slider> - Accessible range slider custom element with keyboard support.
• <rapi-doc> - Web component for creating documentation from OpenAPI Specification.
• <shader-doodle> - Web component for writing and rendering shaders.
• <trix-editor> - Rich text editor custom element for everyday writing.
• <vime-player> - Customizable, extensible, accessible and framework agnostic media player.
• <web-vitals> - Bring web vitals quickly into your page using custom elements.

Component Libraries

• AMP - Web component framework for easily creating user-first websites, stories, ads, emails and more.
• Apollo Elements - Custom elements for using Apollo GraphQL with various web components libraries.
• AXA Pattern Library - AXA CH UI components library built with Web Components.
• Blackstone UI - Web components for creating interfaces by Blackstone Publishing.
• Blaze UI Atoms - Set of web components powered by Blaze CSS.
• Brightspace UI core - Collection of web components for building Brightspace applications.
• Clever components - Collection of Web Components made by Clever Cloud.
• DataFormsJS - Standalone Components for SPA routing, displaying data from web services, and more.
• elements-sk - Collection of custom elements for “a la carte” web development.
• github-elements - GitHub’s Web Component collection.
• Elix - High-quality, customizable web components for common user interface patterns.
• Immersive Custom Elements - Set of web components for embedding immersive (VR & AR) content.
• Iooxa - Web components for interactive scientific writing, reactive documents and explorable explanations.
• Joomla UI custom elements - Compilation of Joomla 4 Custom Elements.
• Ketch.UP - Web components library for Sme.UP.
• Lion Web Components - Set of highly performant, accessible and flexible Web Components.
• LRNWebComponents - ELMS:LN produced web components for any project.
• Lume - Custom elements for defining 2D or 3D scenes rendered with CSS3D or WebGL.
• Microsoft Graph Toolkit - Collection of web components for the Microsoft Graph.
• Nightingale - Data visualisation web components for the life sciences.
• Nuxeo Elements - Components for building web applications with Nuxeo using Web Components.
• Open Business Application Platform Web Components - Collection of web components designed for business applications.
• Pixano Elements - Re-usable web components dedicated to data annotation tasks.
• Shoelace - A forward-thinking library of web components.
• Smart Web Components - Web components for business applications.
• TEI Publisher Components - Collection of web components used by TEI Publisher and apps generated by it.
• Tradeshift Elements - Reusable Tradeshift UI Components as Web Components.
• Vaadin components - Evolving set of high-quality web components for building business web applications.
• Warp View - Collection of charting web components for Warp 10.
• Wired Elements - Set of common UI elements with a hand-drawn, sketchy look.
• Wokwi Elements - Web Components for Arduino and various electronic parts.
• XWeather - Collection of web components implementing portions of the OpenWeatherMap API.

Design Systems

• Amber Components - Web Components implementation of the Amber Design System.
• Bolt Design System - Twig and Web Component-powered UI components, reusable visual styles and tooling.
• Calcite Components - Shared Web Components for Esri’s Calcite design framework.
• Carbon Custom Elements - Carbon Design System variant on top of Web Components.
• Chameleon Web Components - Collection of framework-agnostic elements based on the Chameleon Design System.
• Clarity Core Web Components - Suite of web components from the Clarity Design System.
• Crayons - Collection of web components that adheres to the Freshworks Design System.
• FAST Components - Library of Web Components based on the FAST design language.
• Fluent UI Web Components - Library of Web Components that supports Microsoft’s Fluent design language.
• GOV.UK Web Components - Set of encapsulated web components consuming the GOV.UK Design System.
• Helix UI - Web Component library for the Helix Design System.
• Lyne Components - Building blocks of the Lyne Design System are based on Web Components.
• Material Web Components - Material Design implemented as Web Components.
• NuML | NUDE Elements - HTML Framework and Design System based on Web Components and runtime CSS generation.
• PatternFly Elements - Collection of flexible and lightweight Web Components based on the Unified Design Kit.
• Pearson Web Components - Pearson’s shareable component library implementing Gravity design system.
• Spectrum Web Components - Adobe Spectrum design language implementation built with Web Components.
• UI5 Web Components - Set of reusable UI elements implementing SAP Fiori Design Guidelines.
• U-M Library Design System - University of Michigan Library Design System.
• Zooplus web components - Set of web components that implement Z+ shop style guide.

Use Cases

• How we chose to build our Design System using StencilJS Web Components
• How searching for a bundle-free React led me to web components
• Reasons Web Components are perfect for a big company
• 5 Reasons Web Components Are Perfect for Design Systems
• Web components: the secret ingredient helping power the web
• Web Components for Enterprise. Part 1: Salesforce, Oracle, SAP
• Web Components for Enterprise. Part 2: Nuxeo, Ionic, Vaadin
• Why I use Web Components - My use cases
• Why we use Web Components by [@viljamis](https://twitter.com/viljamis)
• Why we use Web Components by [@maxlynch](https://twitter.com/maxlynch)

Libraries

Class Based

• Corpuscule - Small Web Components framework based on decorators.
• DNA - Progressive Web Components library.
• FAST Element - Lightweight library for building performant, memory-efficient, standards-compliant Web Components.
• LitElement - Simple base class for creating fast, lightweight web components. Part of the Polymer Project.
• Lightning Web Components - blazing fast, enterprise-grade Web Components foundation.
• Omi - Next generation web framework in 4kb JavaScript (Web Components + JSX + Proxy + Store + Path Updating).
• Panel - Web Components + Virtual DOM: web standards for powerful UIs.
• Polymer - Original web component library by the Polymer Project authors.
• Skate - Web component library focusing on a functional rendering pipeline and a small footprint.
• slim.js - Fast & Robust Front-End Micro-framework based on modern standards.
• Stencil - Compiler for generating Web Components.
• Tonic - Minimalist, stable, audit friendly component framework.

Functional

• atomico - Small library for the creation of interfaces based on web components using functions and hooks.
• fuco - Functional component like React, but for Web Components.
• haunted - React’s Hooks API implemented for web components.
• hybrids - UI library for creating Web Components with simple and functional API.
• Solid - Declarative JavaScript library for creating user interfaces.

Integrations

• ember-custom-elements - Render Ember and Glimmer components using custom elements.
• preact-custom-element - Generate/register a custom element from a preact component.
• [@adobe/react-webcomponent](https://github.com/adobe/react-webcomponent) - Automate the wrapping of a React component in a custom element.
• react-shadow - Utilise Shadow DOM in React with all the benefits of style encapsulation.
• reactify-wc - Use web components with React properties and functions.
• remount - Mount React components to the DOM using custom elements.
• [@riotjs/custom-elements](https://github.com/riot/custom-elements) - Simple API to create vanilla custom elements with Riot.js.

Benchmarks

• All the Ways to Make a Web Component
• web-components-benchmark - Benchmark Web Components technologies with various examples.
• web-components-todo - The same todo application built in different Web Components libraries for benchmark purpose.

Frameworks

Angular

• Angular Elements Overview
• Building and consuming Angular Elements as Web Components
• How to use Angular ngModel and ngForms with WebComponents
• Using Web Components in Angular
• Web Components With Angular Ivy In 6 Steps

React

• Rendering React Components With Custom Elements
• How to use Web Components in React

Vue

• Create & Publish Web Components With Vue CLI 3
• Get started with Vue web components
• Integrate Web Components with Your Vue.js App
• Using Web Components in Vue

Svelte

• Svelte Custom Element API
• How to Create a Web Component in Svelte
• Svelte Web Component — 5.4KB

Ecosystem

Starter Kits

• Create Open Web Components - Web component project scaffolding.
• custom-element-boilerplate - Boilerplate for creating a custom element.
• hello-web-components - Simple starter hello world web component written in TypeScript.
• nutmeg - Build, test, and publish vanilla Web Components with a little spice.

Tools

• Custom Elements Locator - Chrome extension to find custom elements on a page.
• query-selector-shadow-dom - querySelector that can pierce Shadow DOM roots, useful for automated testing.
• shadow-automation-selenium - Shadow DOM automation using Selenium.
• shadow-dom-utils - Set of useful utilities for dealing with shadow DOM, primarily for test environment.
• [@storybook/web-components](https://www.npmjs.com/package/@storybook/web-components) - UI development environment for plain web-component snippets.
• webcomponents.dev - Component IDE for web platform developers.
• web-component-analyzer - CLI that analyzes web components and emits documentation / diagnostics.
• Web Components Codemods - Codemods for Web Components.

Books

• Web Components in Action - Book by Ben Farrell, available at Manning early release program.
• Web Component Essentials - Book by Cory Rylan, early preview edition available at Leanpub.

Tutorials

• “Let’s Build Web Components!” by Benny Powers
  • Part 1: The Standards
  • Part 2: The Polyfills
  • Part 3: Vanilla Components
  • Part 4: Polymer Library
  • Part 5: LitElement
  • Part 6: Gluon
  • Part 7: Hybrids
• “Web components: from zero to hero” by Pascal Schilp
  • Part 1: An introduction to writing raw Web Components
  • Part 2: Supercharging Web Components with lit-html
  • Part 3: Web Components hero with LitElement
• “The Modern JavaScript Tutorial” by Ilya Kantor
  • Part 1: From the orbital height
  • Part 2: Custom Elements
  • Part 3: Shadow DOM
  • Part 4: Template element
  • Part 5: Shadow DOM slots, composition
  • Part 6: Shadow DOM styling
  • Part 7: Shadow DOM and events
• “HowTo: Components” by Web Fundamentals
  • Overview
  • <howto-checkbox>
  • <howto-tabs>
  • <howto-tooltip>
• CSS tricks article series by Caleb Williams
  • Part 1: An Introduction to Web Components
  • Part 2: Crafting Reusable HTML Templates
  • Part 3: Creating a Custom Element from Scratch
  • Part 4: Encapsulating Style and Structure with Shadow DOM
  • Part 5: Advanced Tooling for Web Components
• Angular Elements article series by Manfred Steyer
  • Part I: A Dynamic Dashboard In Four Steps With Web Components
  • Part II: Lazy and External Web Components
  • Part III: Angular Elements Without Zone.Js
  • Part IV: Content Projection with Slots in Angular Elements (>=7)
  • Part V: Your Options for Building Angular Elements with the CLI

Insights

Podcasts

• Code[ish], episode 38: Building with Web Components
• Frontend Happy Hour, episode 62: Web Components - shots of shadow DOM
• Labs Talk - Web Components with Peter Muessig
• Real Talk JavaScript, episode 7: Custom Web Components with Rob Wormald
• Real Talk JavaScript, episode 101: Back to Basics with Native HTML and LitElement

Presentations

• Are Web Components the Betamax of web development? by [@lostinbrittany](https://twitter.com/lostinbrittany)
• Designing Standard Systems by [@stefsull](https://twitter.com/stefsull) and [@bferrua](https://twitter.com/bferrua)
• Frontend Architecture for Scalable Design Systems by [@salem_cobalt](https://twitter.com/salem_cobalt)
• lit-apollo: Data-Driven Components that Use the Platform by [@PowersBenny](https://twitter.com/PowersBenny)
• Mastering Shadow DOM by [@Martine_Dowden](https://twitter.com/Martine_Dowden)
• Modernizing Large Frontends with Web Components by [@samjulien](https://twitter.com/samjulien)
• Shadow DOM: off the beaten track by [@serhiikulykov](https://twitter.com/serhiikulykov)
• Using Web Components to Build a Framework-agnostic UI Library by [@brianbouril](https://twitter.com/brianbouril) and [@danciupuliga](https://twitter.com/danciupuliga)
• Web Components and the AOM by [@LeonieWatson](https://twitter.com/LeonieWatson)
• Web Components and Styles Scoping by [@bashmish](https://twitter.com/bashmish)
• Web Components can do that?! by [@vogloblinsky](https://twitter.com/vogloblinsky)
• Web Components: Introduction and State of the Art by [@webcomp_dev](https://twitter.com/webcomp_dev)

Talks

• Better Apps: Delivering Universal UI Patterns as Web Components by [@janmiksovsky](https://twitter.com/janmiksovsky)
• Custom Web Shadow Elements, or Whatever… by [@aerotwist](https://twitter.com/aerotwist)
• Styling and Theming Web Components by [@justinfagnani](https://twitter.com/justinfagnani)
• Web Components at Enterprise Scale by [@diervo](https://twitter.com/diervo)

Usage Metrics

• Chrome Platform Status: CustomElementRegistryDefine
• Chrome Platform Status: ElementAttachShadow
• Chrome Platform Status: HTMLTemplateElement

Proposals

Form-associated Custom Elements

• Form Participation API Explained - Document by Google Chrome team.
• Form-associated custom elements - Feature in Chrome platform status.
• web-platform-tests

Custom State Pseudo class

• Blink: Intent to implement
• ElementInternals’s states property and the :state() pseudo class

Constructable Stylesheet Objects

• Specification Draft
• web-platform-tests
• Explainer
• Constructable Stylesheets - Feature in Chrome platform status.

Miscellaneous

• bruck - Prototyping system built with web components and the Houdini Paint API.
• Vaadin Directory - Publish, discuss and rate web components
• webcomponents.org - Discuss & share web components.

History

The articles below represent a long story of the Web Components specifications on the way towards the standardization. Some of them refer to earlier, so-called “v0” Shadow DOM and Custom Elements specs, and abandoned HTML Imports spec. These materials are here for historical reasons only, they are grouped by years and listed in chronological order.

2019

• A history of the HTML slot element
• Web Components in 2019: An Overview of the Most Exciting Proposals for the Web Platform Related to Web Components

2018

• Styling Accessibility: A Web Components Approach
• Web Components 101: An Introduction to Web Components
• Web Components in 2018
• Web Components Introduction: Creating Custom HTML Elements in 2018

2017

• Web Components: The Long Game
• An intro to web components with otters
• The broken promise of Web Components
• Regarding the broken promise of Web Components

2016

• Introducing Custom Elements
• The Case for Custom Elements: Part 1
• The Case for Custom Elements: Part 2
• Demythstifying Web Components
• What’s New in Shadow DOM v1 (by examples)
• Understanding Web Components

2015

• Introducing Slot-Based Shadow DOM API
• Web Components and their role in the future of web development
• Microsoft Edge and Web Components
• Bringing componentization to the web: An overview of Web Components
• The state of Web Components

2014

• A No-Nonsense Guide to Web Components
• Mozilla and Web Components: Update
• The State of the Componentised Web
• Building an Accessible Disclosure Button – using Web Components
• Web Components and you – dangers to avoid
• The Web’s Declarative, Composable Future
• The Shadow DOM Diaries
• A Detailed Introduction To Custom Elements

2013

• Performance and Custom Elements
• A Guide to Web Components
• Creating Reusable Markup with The HTML Template Element
• Working with Shadow DOM
• HTML’s New Template Tag

2012

• The Basics of the Shadow DOM
• Notes on Web Components + ARIA
• Introduction to Web Components

2011

• Web Components and Model Driven Views by Alex Russell
• What the Heck is Shadow DOM?

Who To Follow

Polymer	Stencil	open-wc.org	webcomponents.dev
Justin Fagnani	Viljami Salminen	Jan Miksovsky	Serhii Kulykov

License

Copyright 2014-2018, All rights reserved.

Code licensed under the: MIT license

@author Mateus Ortiz mteusortiz@gmail.com