About a year ago in May 2013, Google launched Polymer.js.

So here we are, a year later. And the question is: Is it yet ready for prime time? Is it yet possible to create a production ready application using Polymer web development techniques?

To answer this question, I took Polymer out for a test drive to develop a web application and to see how well it would behave. This article is about that experience and what I learned in the process.

Polymer.js: The Concept

Before we get into our Polymer tutorial, let’s first define Polymer.js, not for what it claims to be, but for what it actually is.

When you begin to check out Polymer, you can’t help but immediately be intrigued by its self-professed unique world view. Polymer purports itself as taking a sort of back-to-nature approach that “puts elements back at the center of web development”. With Polymer.js, you can craft your own HTML elements and compose them into complete, complex web applications that are scalable and maintainable. It’s all about creating new (i.e., custom) elements that can then be reused in your HTML pages in a declarative way, without needing to know or understand their internals.

Elements, after all, are the building blocks of the web. Accordingly, Polymer’s weltanschauung is that web development should fundamentally be based on extending the existing element paradigm to build more powerful web components, rather than replacing markup with “gobs of script” (to use their words). Stated another way, Polymer believes in leveraging the browser’s “native” technologies rather than relying on an increasingly complex labyrinth of custom JavaScript libraries (jQuery et. al.). An intriguing notion indeed.

OK, so that’s the theory. Now let’s take a look at the reality.

Polymer Web Development: The Reality

While Polymer’s philosophical approach certainly has merit, it is unfortunately an idea that (at least to some extent) is ahead of its time.

Polymer.js places a hefty set of requirements on the browser, relying on a number of technologies that are in still in the process of standardization (by W3C) and are not yet present in today’s browsers. Examples include the shadow dom, template elements, custom elements, HTML imports, mutation observers, model-driven views, pointer events, and web animations. These are marvelous technologies, but at least as of now, that are yet-to-come to modern browsers.

The Polymer strategy is to have front-end developers leverage these leading-edge, still-to-come, browser-based technologies, which are currently in the process of standardization (by W3C), as they become available. In the meantime, in order to fill the gap, Polymer suggests the use of polyfills (downloadable JavaScript code which provides features that are not yet built into today’s browsers). The recommended polyfills are designed in such a way that (at least theoretically) will be seamless to replace once the native browser versions of these capabilities become available.

OK, fine. But let me get this straight. At least for now, we’re going to use JavaScript libraries (i.e., polyfills) to avoid the use of JavaScript Libraries? Well, that’s “fascinating”.

The bottom line, then, is that we’re in a sort of limbo mode with Polymer, as it is ultimately relying on (or perhaps more accurately, approximating) browser technologies that don’t yet exist. Accordingly, Polymer.js today seems more like a study in how element-centric applications may be built in the future (i.e., when all the necessary features are implemented in the major browsers and polyfills are no longer needed). But, at least at present, Polymer seems more like an intriguing concept than an actual option for creating robust change-your-view-of-the-world applications right here and now, which makes writing (or finding) a Polymer tutorial difficult outside of Google’s documentation.

Polymer Architecture

Now, onto our guide. Polymer.js is architecturally divided into four layers:

Native: Needed features currently available natively in all major browsers. Foundation: Polyfills that implement needed browser features not yet natively available in the browsers themselves. (The intention is for this layer to disappear over time as the capabilities it provides become available natively in the browser.). Core: The necessary infrastructure for Polymer elements to exploit the capabilities provided by the Native and Foundation layers.. Elements: A basic set of elements, intended to serve as building blocks that can help you create your application. Includes elements that provide: Basic functionality like ajax, animation, flex layout, and gestures. Encapsulation of complicated browser APIs and CSS layouts. UI component renderers such as accordions, cards, and sidebars.

This image guide shows the 4 architectural layers of Polymer.js web developerment.

Creating a Polymer Application

To get started, there are some articles and tutorial write-ups that help introduce you to Polymer, its concepts, and its structure. But if you’re anything like me, when you’ve gone through them and are ready to actually build your application, you quickly realize that you’re really not quite sure where to start or how to create it. Since I’ve now gone through the process and figured it out, here are some pointers…

Polymer web development is all about creating elements, and is only about creating elements. So, consistent with the Polymer world view, our application is going to be… a new element. Nothing more and nothing less. Oh OK, I get it. So that’s where we start.

For our Polymer project example, I’ll name the top-level element of the application , since custom element names (regardless of what framework you use to create them) must include a hyphen (e.g., x-tags, polymer-elements, etc.).

The next step, though, requires quite a bit more thought. We need to decide on how we are going to componentize our application. An easy approach is just to try to identify, from a visual perspective, the components in our application and then try to create them as custom elements in Polymer.

So for example, imagine that we have an app with the following screens:

This tutorial image depicts three Polymer.js web development screens in action.

We can identify that the top bar and the side bar menu are not going to change and the actual “content” of the app could load different “views”.

That being the case, one reasonable approach would be to create the element for our app and, inside that element, we could use some Polymer UI Elements to create the top bar and the side bar menu.

We can then create our two main views, which we’ll call ListView and the SingleView, to be loaded into the “content” area. For the items in the ListView, we can create an ItemView.

This will then yield a structure something like this:

This is a demo of an example Polymer.js structure.

The Good News

Now that we have our example Polymer application, we can insert it into any web page just by importing our “toptal-app.html” and adding the tag because, after all, our app is just an element. That’s cool.

In fact, therein does lie much of the power and beauty of the Polymer paradigm. The custom elements you create for your application (including the top-level one for your entire application) are treated as any other element in a web page. You can therefore access their properties and methods from any other JavaScript code or library (e.g., Backbone.js, Angular.js, etc.). You can even use those libraries to create your own new elements.

Moreover, your custom components are compatible with other custom element libraries (such as Mozilla’s X-Tag). So it doesn’t matter what you use to create your own custom element, it is compatible with Polymer and any other browser technology.

It’s therefore not surprising that we’ve already started to see the advent of a community of Element Creators that expose and share their newly created elements in forums like the Custom Elements site. You can go there and grab whatever component you need and just use it in your application.

On the other hand…

Polymer is still sufficiently new technology that developers, especially novice app developers, are likely to find it to be somewhat brittle, with a number of not-so-hard-to-find rough edges.

Here’s a sampling:

  • Lack of documentation and guidance.
    • Not all Polymer.js UI and non-UI Elements are documented. Sometimes the only “guidance” on how to use them is demo code. In some cases, it’s even necessary to refer to the source code of a Polymer Element to understand better how it works and can/should be used.
    • It’s not entirely clear how to organize larger applications. In particular, how are you supposed to pass singleton objects between elements? Which strategy should you employ to test your custom elements? Guidance on these types of issues at this point is scant at best.
  • Dependency errors and version-itis. Even when you download Polymer.js elements as is recommended, you might find yourself with a dependency error, pointing to different version dependencies in the same element. While it is understood that Polymer Elements are currently under heavy development, these kind of problems can make development quite challenging, eroding developer confidence and interest.

  • Problems on mobile platforms. Polymer.js performance on mobile platforms can often be somewhere between frustrating and problematic.
    • Downloading the entire library and polyfills (without gzip’ing) is slow, and you need to download every Polymer Element that you intend to use.
    • Processing the polyfills, libraries, and custom elements appears to be an expensive task on mobile platforms. Even when the downloading is complete, you still often have a blank screen for a few seconds.
    • Especially for more complex functionality (such as drag-and-drop or rendering into a canvas), you may find that functionality that works fine on the desktop simply does not work properly, or is not yet supported, on the mobile platform. In my particular case, one such frustration that I encountered was with rendering into a canvas on iOS.
  • Inadequate or confusing error reporting. Sometimes when you misspell an attribute name, or just break something related to the core layer itself, you receive a strange error message on your console with two call stacks that you need to investigate to try determine where the problem is. Sometimes it’s easy to solve this, but sometimes you end up needing to try a completely different strategy just to avoid the error since you can’t track down it’s source.


Polymer is intriguing technology, but it is undeniably still in its infancy. As such, it’s not yet well suited to development of a large, enterprise level, production-ready application. Additionally, there aren’t many guides or tutorials available specific to Polymer.js web development.

As far as whether the JavaScript-centric or DOM-centric approach is really fundamentally better, the jury is still out. Polymer makes some convincing arguments, but counter-arguments do exist.

Perhaps most notably, Polymer requires a fairly significant level of expertise in using browser technologies like the DOM. You’re in many ways returning to the days before jQuery, learning the DOM API to do simple tasks like adding or removing a CSS class from an element. This certainly does make it feel, at least on some level, like you’re taking a step backward rather than forward.

But that said, it does appear likely that custom elements are going to be an important part of Web Development in the future, so diving in sooner rather than later would probably be prudent for today’s web developer. And if you’ve never tried to create your own custom elements before, Polymer (and this tutorial) is probably a sensible place to start.

About the author

Alejandro Hernandez, Argentina
member since August 30, 2012
Alejandro got his Bachelor's in software engineering eleven years ago, and since then has been working for software companies of all sizes from all around the globe as a freelancer. Currently, he enjoys working as the technical lead on JavaScript projects, where his deep understanding of architecture and theory is most impactful. [click to continue...]
Hiring? Meet the Top 10 Freelance Front-End Developers for Hire in October 2016


Jay Johnston
Alejandro, great post, and thanks for the introduction to where the rough edges are. This is really helpful!
Adrian Miu
If a moderately complex website needs some custom elements plain HTML+CSS+JS is a good choice (eg: Bootstrap tabs and accordions) and JS plugins are good enough (eg: jQuery UI sliders as input elements). A full-featured HTML app on the other hand will require some kind of framework. Angular, Ember, CanJS allows you to create custom elements without the additional weight. I don't find the selling points (shadow dom etc) convincing enough to use this library.
Interestingly, most of these technologies (custom elements, MVC, ...) have been here before as XForms. However, they were never a mainstream success as browser vendors never implemented XSLT. Also, XForms implementation were pretty bad and so the technology got forgotten. I am quite glad that so many popular JS frameworks are now bringing back this nice techniques and ideas behind it. Polymer certainly is coming closest to XForms (and XML people are actually quite excited by it) and I think it will be interesting to see if if will be a mainstream success. For sure the chances are much better as web developer seem to hold a grudge against XML and X-technologies (XSLT, XQuery, XPath, ...) and love JavaScript. Never understood why, though...
Thanks. Well written.
Sorry for going off-topic, but what did you use to create that mockup (the second image in the article)? Looks really nice.
Luboš Volkov
Hi, This illustration have been made in the Adobe Photoshop.
Kris Khaira
Aah. I thought there was a cool wireframing tool out there that could make wireframes that looked that nice. Nice work.
Julio Szabo
It is always a pleasure read your posts. Congrats!!!
Brad Sturtevant
React framework used by Facebook creates a shadow dom of its own, and achieves significant speed advantages over AngularJS when creating large forms with validation and effects. Google's response is that browsers will automatically handle shadow dom so why put it in a component library now. In either case shadow dom is a proven way to improve performance whether it's a library of components or browsers in the future. I can't really see why you would not support a polyfill for such things, and it's just ridiculous to assert that component developers thought javascript was going away. You might follow up I fear to say that C++ developers were really thinking C standard lib was going away :-) Just making components you know.
Hard Luck
Has compatibility issues with ajax requests on firefox?
That's a mere question of time when Angular will switch towards native web components, it unsurprisingly already emulates them to a large degree for compatibility reasons. Not a coincidence that the proposals come from Google mostly.
Osama Mursleen
Great article.
Rohit Ghatol
Very Well Written.....
Christopher Reid
One does not simply... add or remove a class from an element without JQuery. Haha, anyways, thanks, great article.
avi tshuva
Why there is no DATE to posts in this site?!?
Matthew Davidson
I don't understand why polymer wouldn't go the distance and support package managers like component or npm-browserify. ONLY using bower for package management seems like a great way to say "not really modular" because you can't actually just ship it ANYWHERE.
Erik Ringsmuth
A quick note: React doesn't have shadow DOM it has a virtual DOM. Shadow DOM is all about encapsulation of HTML, CSS, and Javascript events. Virtual DOM is a parallel Javascript version of the HTML DOM that is tied to the HTML. The idea is that JS is fast and HTML is slow. If you can update the JS and have it reflected in the HTML through the virtual DOM you gain performance. This is what React did. Polymer uses shadow DOM but also something equivalent to React's virtual DOM. Polymer templates are native <template> tags. These contain parsed HTML unlike Angular templates which are strings of unparsed HTML. Polymer's templating system keeps track of the native DOM elements so that an update to the JS will reflect in the HTML DOM the same way that React does it. http://www.polymer-project.org/docs/polymer/databinding-advanced.html#how-data-binding-works One additional thing is that <template> tags in HTML Imports can be parsed in parallel on a different thread since they're not part of the main DOM. The parsing doesn't block the main document. More speed for Polymer/Web Components!
Erik Ringsmuth
"You’re in many ways returning to the days before jQuery" Yes, in a good way! jQuery existed to fill in the gaps between browsers. However, in modern browsers, you might not need jQuery http://youmightnotneedjquery.com/. I say that with some caveats. Some things are definitely made simpler with a library like jQuery. Javascript MVC frameworks were created for similar reasons as jQuery. They filled in all of the gaps that the native DOM didn't support. Web Components add so much of this to the native DOM. But... not everything. That's where Polymer comes in. Polymer fills in the gaps that native web components don't do. Here are the main things we got from JS MVC frameworks: MVC -> Custom Elements (native or Polymer) Templating / data binding -> <template> (native), Polymer data binding Event Handling -> CustomEvents (native), Polymer event mapping Routing -> server routing, <app-router>, <flatiron-director> Modules / DI -> HTML Imports (native), System.import() (native) The biggest win is the complete interoperability of components. The API is always native HTML. Any library that builds on top of this will work alongside any other library. That's the future if you ask me!
Great article, Alejandro! Just to be clear, even the folks at Polymer don't think it's ready for prime time. They prominently post warnings saying "under development" and "things may break!" all over the place. I think the Polymer folks are getting on a train before it leaves the station. All the polyfill cruft will eventually drop out as browsers modernize, and HTML5 elements are going to be a large part of the future. The question isn't whether developers will use them, but how. The polymer project is aimed at helping folks make the transition and making sure that decent tools exist for after the transition. They are also making sure that material design is an easy option going forward. My takeaway from reading your article and the polymer materials linked to it: even if you love javascript and css, writing custom elements is a great way to break up your code into reusable chunks. That's just good programming! But that doesn't mean you should use Polymer for a mission-critical site yet. It's going to change and things may break.
max weinbrown
Also, the concept of reusable web-components is being approximated/simulated pretty well in Ember, as... Components. They are working hand-in-hand with the spec to ensure compatibility when it's done.
Polymer tutorial & example https://www.youtube.com/watch?v=QbcHYs-OReY#t=33
tukul biswas
great... Added more content to already confused developers...
vikram kumar
Great analysis of polymer strengths and weaknesses. http://kumarvikram.com
Filip Dupanović
Bower already added dependency resolution, packaging and distribution and you can start a private registry faster than you can say bowerbird. The fact that you can bring your own build tools is considered a feature. It would be incredibly annoying if I pulled your seemingly independent package, but had to install additional tools and run additional commands before I could test the client-side sources.
Max Waterman
Perhaps it's time to revisit this question. I've successfully used it in fairly significant projects that target only chrome/chromeos with very few issues. I know others will want to target more than just chrome(os) just I'm curious where polymer stands these days, after another year.
Paul Sirous
You're right, polymer is a quiet new technology and has some weak places like different versions of components in dependencies. But this is common problem that is +/- being solved in other frameworks (e.g. Bower, Bundles etc.) so considering the small age of polymer, we can assume they also will find a way how to deal with it. My other point regarding lack of documentation, well, by exploring framework's source you gonna be better specialist ( compared to others) by the time when they make good docs and everybody can figure out how to master apps with it :))
I am exploring more about Polymer, and this post is well done. Thanks for sharing your views .
Shahid Durrani
The Web is different, and I can see why programmers might have little tolerance for the paths it chose, but this time the programmers are wrong It’s not that the Web is perfect – it certainly has glitches. It’s not that success means something is better.
Astrill Arnold Chitwa
Brother i have been looking for a confident introduction to web components and Polymer and i must admit it,wow hands down, you really know how to teach objectively, you create a good entry point for so many people including myself in understanding complex things such as this. Am more confident to take Polymer for a spin just outta the confidence that i have built from this. Lastly i think you should explore this topic more deeply and probably author a book with this approach you may be single-handedly responsible for the early adoption of this tech - no one is doing anything greater at explaining this like you did here, not even the guys from Google. God Bless
Rodney Barbati
One of the things I like most in polymer is that the html, javascript and even css are integrated into a custom element - in the same file, and not via includes. When you want to use the component, you import it (the single .html file) and you are done. It moves us closer to the dream of object orientation on the web.
one gotta love articles without publish date... oh man, why! why! whyyy!!!???
comments powered by Disqus
The #1 Blog for Engineers
Get the latest content first.
No spam. Just great engineering and design posts.
The #1 Blog for Engineers
Get the latest content first.
Thank you for subscribing!
You can edit your subscription preferences here.
Trending articles
Relevant technologies
About the author
Alejandro Hernandez
JavaScript Developer
Alejandro got his Bachelor's in software engineering eleven years ago, and since then has been working for software companies of all sizes from all around the globe as a freelancer. Currently, he enjoys working as the technical lead on JavaScript projects, where his deep understanding of architecture and theory is most impactful.