View on Github

Web Components the Right Way


This is a guide intended to introduce to Web Components. Everyone can contribute here!

Web Components the Right Way was made with love by Mateus Ortiz



  • a place to discuss and evolve web component best-practices
  • Polymer Blog The latest goings-on with the Polymer project and in the community.



  • Ten Principles for Great General Purpose Web Components This page lays out a set of principles for creating general-purpose web components that can be readily adopted in a wide range of sites and application.
  • Modular future Web Components A Guide to Web Components
  • Web Components é uma Revolução? PT-br Existe uma nova celebridade na cidade, e seu nome é "Web Components". Ultimamente muitos apresentam esta nova tecnologia como o 'Santo Graal' que vai resolver todos os problemas da Web. Este artigo não é um apoio incondicional, não é uma crítica negativa irrefutável, mas meramente uma apresentação de perspectivas com o objetivo de dar clareza.
  • The State of the Componentised Web The idea of building applications out of a number of independent components isn’t anything new. But with Web Components is a good time to look at component-based application development, how we benefit from taking this approach, how we can build our applications in this way using existing technologies and how we’re likely to be building our front-end web apps in the future.
  • Web Components and their role in the future of web development A discussion surrounding the history and future of Web Components in modern web development.
  • A No-Nonsense Guide to Web Components A multi-part series with a crash course on Web Components specs, polyfills, performance, accessibility, and more.
  • Understanding Web Components Another overview of web components specs and explanation of their advantages: composability, encapsulation, reusability.
  • Demythstifying Web Components An attempt to conclusively curb stomp the seemingly endless FUD that circulates about Web Component

Custom Elements

Shadow DOM


HTML imports

  • Exploring HTML Imports Web Components have come a long way in the past few months. HTML Imports allow you to load additional documents into your page without having to write a bunch of ajax. This is great for Custom Elements where you might want to import a suite of new tags.


  • Aurelia - Aurelia is a JavaScript client framework for mobile, desktop and web leveraging simple conventions and empowering creativity.
  • Polymer vs Angular 2 Which one should I choose?
  • Polymer vs. X-Tag Polymer vs. X-Tag - Here's the difference
  • Polymer vs Angular Here’s the difference between Polymer and Angular



  • Generator Elements A Yeoman Generator that provides a functional boilerplate to easily create Custom Elements using Polymer, X-Tag or VanillaJS.
  • Generator Polymer Yeoman generator for scaffolding Polymer apps
  • Geneator X-Tag X-Tag generator for Yeoman
  • Slush Element A Slush Generator that provides a functional boilerplate to easily create Custom Elements using Polymer, X-Tag or VanillaJS.



Best Practices

Style Guides

  • Google Web Components Style Guide This guide serves as an extension to the Google JavaScript Style Guide with additional style guidance around authoring Web Components, particuarly those in this element collection. It is targeted at Google engineers, but may be useful for others too.
  • Polymer Elements Style Guide



  • Polymer Polymer is a new type of library for the web, built on top of Web Components, and designed to leverage the evolving web platform on modern browsers.
  • X-Tag X-Tag is a small JavaScript library, created and supported by Mozilla, that brings Web Components Custom Element capabilities to all modern browsers.
  • Bosonic Bosonic is a set of tools that enable you to build Web Components as the spec currently describes, and supporting not-so-modern browsers like IE9.
  • Polymer Dart Polymer.dart is a Dart port of Polymer. Build Web Components with Dart, and interoperate with Web Components built with JavaScript.
  • Skate Skate is a web component library that is focused on being a tiny, performant, syntactic-sugar for binding behaviour to custom and existing elements without ever having to worry about when your element is inserted into the DOM.
  • Bit Bit lets you easily create reusable web components from any context. You can store and organize your components together and still find, modify, test and use them individually in any application.



  • Are We Componentized Yet? Tracking the progress of Web Components through standardisation, polyfillification, and implementation.


  • Vulcanize Concatenate a set of Web Components into one file


  • WebComponentsjs: A polyfill for Custom Elements, Shadow DOM, HTML Imports, Weakmap, and Mutation Observers
  • custom-elements: A polyfill for the v1 spec for Custom Elements.


Who To Follow

Eric Bidelman Addy Osmani Rob Dodson Web Components Polymer
Eric Bidelman Addy Osmani Rob Dodson Web Components Polymer
Alex Komoroske Pascal Zeno Rocha Daniel Buchner Angelina Fabbro
Alex Komoroske Pascal Precht Zeno Rocha Daniel Buchner Angelina Fabbro
Eduardo Pascal Hartig Sindre Sorhus Christian
Eduardo lundgren Pascal Hartig Sindre Sorhus Christian Heilmann


Copyright 2014, All rights reserved.

Code licensed under the: MIT license

@author Mateus Ortiz