Menu Search
Jump to the content X X
Smashing Conf Barcelona

You know, we use ad-blockers as well. We gotta keep those servers running though. Did you know that we publish useful books and run friendly conferences — crafted for pros like yourself? E.g. our upcoming SmashingConf Barcelona, dedicated to smart front-end techniques and design patterns.

A Responsive Material Design App With Polymer Starter Kit

One upcoming technology that represents a big leap forward in making the web a mature application platform is web components1. From a high-level perspective, web components will enable better composability, reusability and interoperability of front-end web application elements by providing a common way to write components in HTML.

The goal of this article is to show you why this will be such an important step, by showing off what can be accomplished right now using Polymer2. Polymer is currently the most advanced and (self-proclaimed) production-ready library based on web components.

Further Reading on SmashingMag: Link3

What Is Polymer? Link

Let’s get this out of the way: “Polymer is not a framework.” The team behind it strongly emphasized this at this year’s Google I/O talk about the 1.0 release. Polymer was announced at Google I/O 2013. Its purpose is to enable developers to work with web components and the four underlying low-level APIs — HTML imports8, shadow DOM9, HTML templates and custom elements10 — before the standards are finalized and implemented by all browser vendors.

This is accomplished by providing a set of polyfills that, well, “fake” the new API behavior where it is not yet implemented for the last two versions of all major browsers. Beyond these polyfills, Polymer also provides some syntactic sugar that makes working with web components a bit easier.

One year later, the project got a big boost at Google I/O 2014, as the team announced its ambitions to drive Polymer forward by providing an extensive library of prebuilt elements for developers, based on the material design11 guidelines12. Now, one year later, the “production-ready” 1.0 version of Polymer was officially announced in the I/O 2015 keynote.13

So, let’s take a closer look at what all the fuss is about and what working with web components and Polymer feels like.

The Polymer Components Link

With version 1.0, the Polymer team announced different sets of element product lines14. These reusable building blocks are prebuilt for developers and show how web components will enable an ecosystem of modular building blocks.

  • Iron elements15
    These are utility elements that handle basic layouting and core functionality, without applying any complex visual styles.
  • Paper elements16
    These are a web component implementation of material design based on the iron element.
  • Google web components17
    These web components are wrappers for Google APIs and services. For example, there is an element for Google Maps, YouTube and Google Calendar.
  • Gold elements18
    These are special elements that can be used for e-commerce, such as credit-card input elements.
  • Neon elements19
    All fancy special effects fall under this label. Currently, only a web animations20 element is in there, which has some pretty cool demos21.
  • Platinum elements22
    This category is for components that enable complex web app functionality, such as push notifications.
  • Molecules23
    These elements are wrappers for other JavaScript libraries.

Beyond this official Polymer repository, you should check out Custom Elements5324, a repository of even more elements. These elements are not necessarily based on Polymer but are still compatible thanks to the web component magic.

Example Application Link

Create Boilerplate Using Starter Kit Link

Enough with the high-level talk and overviews. How do we start developing with Polymer? Thankfully, the guys at Google have released25 a neat starter kit26 with version 1.0.

If you have Node.js, npm, Bower and Gulp installed, you can run the following command in the project directory to install all dependencies:

npm install -g gulp bower && npm install && bower install

For additional information on modern JavaScript tooling, check out the respective pages on npm27, Bower28 and Gulp29.

After installing the dependencies, you can run the kit with Gulp:

gulp serve

This command will build and serve the starter kit.

A Look at the Starter Kit Link

What we have here with the starter kit is a very basic application skeleton, with responsive layout, material design, routing functionality and offline caching via the service worker API.

Polymer starter kit30
Polymer starter kit. (View large version31)

Let’s take a closer look at what an application like this looks like under the hood in web component land. Look at the app/index.html file. In the head you can see that the script is included in the page:

<script src="bower_components/webcomponentsjs/webcomponents-lite.js"></script>

This is the web component polyfill part of Polymer, which will become obsolete over time; Can I Use lists its current state32. At the time of writing, web components are supported natively 100% in Chrome and Opera and are currently behind a flag in Firefox.

A bit further down the line, you will find this part:

<link rel="import" href="elements/elements.html">

This is HTML imports in action. When you go further and open the elements/elements.html file, you will see that all of the elements used in the body of index.html are imported here. You could also directly import them into index.html, but the source file is a bit cleaner if you put them into their own .html file.

Now, let’s have a look at the actual markup of the application.

Structure an App With Web Components Link

Most importantly when looking at index.html, you will see a lot of custom elements, which are used to mark up the app. Here, you will see mostly elements from the iron-* and paper-* element libraries33. Custom elements need to be prefixed with this - notation to avoid collision with potential future base HTML elements.

You can see that the complete layout of the page is made up of paper and iron elements from the Polymer library:

   <!--Responsive sidebar drawer -->
      <!-- Header of the drawer -->
      <!--Menu in the drawer -->
   <!--Main content area -->
         <!--Header of the main content -->
         <!--Main content -->

This shows the very declarative and semantic way of structuring an app with web components. Imagine looking at the markup of such an application in a traditional web application; it would have hundreds of divs all over the place.

Web Components as APIs Link

Additionally, you have an example of the platinum-* elements that provide more complex functionality, such as facilitating the new service worker API. Service workers are another new standard API that enables you to create a background service in the browser that can handle caching, an offline experience for your web app and much more. It is not directly related to web components, so check out HTML5 Rocks’ article34 if you want to learn more about it. Similarly, the paper-toast element adds a notification toast functionality to the application. This shows the way web components can be used to capture more complex functionality and APIs.

Overall, the markup of the application shows the very declarative way of marking up an application by combining reusable elements. Notice that there is not a lot of additional JavaScript or CSS throughout the starter kit app. Most of the complex code is nicely encapsulated in the elements that were pulled in as dependencies.

Data Binding and Routing Link

You probably noticed that the application is wrapped in an HTML template tag:

<template is="dom-bind" id="app">

This is done because Polymer uses HTML templates as context (as AngularJS does with the $scope, for example) for data binding.35 The is="dom-bind" shows the is attribute, which is a way to declare that some element is a custom element of the type provided as a value, while still inheriting from the tag it is placed on. So, this template tag gets treated as a dom-bind element, which is a custom element provided by Polymer that now inherits from the template element it was placed on. The dom-bind element here turns on Polymer’s binding capabilities in the template tag it was placed on.

AngularJS developers will probably spot this36 on first sight: The app is held together via data binding with the Mustache syntax. The connection between the paper-menu element and the iron-pages element is a great example of what can be done with this in a web component world.

The paper-menu element, which contains several anchor elements, is responsible for the state of the menu. The selected attribute is bound to the {{route}} variable.

<paper-menu class="list" attr-for-selected="data-route" selected="{{route}}" on-iron-select="onMenuSelect">

The iron-pages element is responsible for filling the main content area with one of its child elements, depending on the state of the selected attribute. Here you can see that the {{route}} variable is being used to connect it with the menu state.

<iron-pages attr-for-selected="data-route" selected="{{route}}">

This data-binding functionality is part of Polymer’s syntactic sugar and is not part of the basic web components standard.

Additionally, to bind the route correctly to a URL, a lightweight router is inside the elements/routing.html file.

page('/', function () {
   app.route = 'home';

page('/users', function () {
   app.route = 'users';

page('/users/:name', function (data) {
   app.route = 'user-info';
   app.params = data.params;

page('/contact', function () {
   app.route = 'contact';

// add #! before urls
   hashbang: true

Here you can see how the route variable is accessed programmatically via app.route. Notice that the template element, used for data binding, has an ID of app. Inside the routing JavaScript code, the data inside the custom element is now available via its ID attribute value; that is why it can be accessed via app.*.

Creating Your Own Custom Elements Link

If you are interested in creating your own custom elements37 with Polymer, you will find the app/elements/my-greeting and app/elements/my-list elements that are defined and used in the starter kit application.

We won’t go in depth into how to create your own reusable elements, though, because that would probably require a whole article of its own.

Adding an Existing Custom Element Link

Let’s go beyond the boilerplate project and add another custom element. How about a Google Map?

Thankfully, there is already an element for that38 in Google’s product line. Adding it to your project is just one bower install away:

bower install --save GoogleWebComponents/google-map#^1.0.0

Now, you can include it with the imported elements in the app/elements/elements.html file:

<link rel="import" href="../bower_components/google-map/google-map.html">

Now that the element is imported, include it in your application — for example, on the “Contact“ screen:

<section data-route="contact">
   <paper-material elevation="1">
      <h2 class="paper-font-display2">Contact</h2>
      <p>This is the contact section</p>
   <paper-material elevation="1">
      <google-map latitude="37.77493" longitude="-122.41942"></google-map>

Some additional CSS is still needed in the app/styles/main.css file to set the display height of the map.

google-map {
   height: 600px;

Voila! You’ve just added a Google Map to your application, without tinkering with any iframe or initializing a JavaScript library.

Adding a Google Map without tinkering with any iframe or initializing a JavaScript library39
Adding a Google Map without tinkering with any iframe or initializing a JavaScript library. (View large version40)

This neatly showcases how developers can take advantage of web components to reuse elements without having to create the same boilerplate or reinvent the wheel. The standard method of adding a Google Map41 to an app without web components is cumbersome by contrast.

Adding a Non-Polymer Custom Element Link

Another thing we might want on the web page is an animated GIF. Go to Custom Elements42 and find the x-gif element43, which promises smooth GIF playback. Unfortunately, it is not based on Polymer. But no problem! It can be added like any other web component.

Again, let’s do a quick bower install to fetch the x-gif component:

bower install --save x-gif

Add it to your app/elements/elements.html imports list:

<link rel="import" href="../bower_components/google-map/google-map.html">
<link rel="import" href="../bower_components/x-gif/dist/x-gif.html">

Put your favorite GIF in app/images/epic.gif, and add it to the home screen using the x-gif tag:

<section data-route="home">
   <paper-material elevation="1">

      <p class="paper-font-subhead">You now have:</p>

      <x-gif src="images/epic.gif"></x-gif>

      <p class="paper-font-body2">Looking for more web app layouts? Check out our <a href="">layouts</a> collection. You can also <a href="">preview</a> them live.</p>


Using the x-gif web component44
Using the the x-gif web component. (View large version45)

Just remember that the x-gif web component has nothing to do with the Polymer library; it is built using the vanilla web components APIs. This really shows the interoperability of web component-based elements. Now, think about how popular frameworks like AngularJS 2.046 and Google Web Toolkit 3.047 will be based on web components in future versions and how much more interoperable frameworks will be in future. By the way, Mozilla is also working on a web component-based library, Bricks48, which is pretty far along in development.

Conclusion Link

We’ve seen now what working with web components in Polymer 1.0 looks like, using the starter kit as a foundation. And we’ve seen the declarative and boilerplate-free way to combine reusable elements, elements that interoperate without necessarily having been developed with the same libraries or frameworks.

I am really excited about web components because they mark a huge step in the advancement of the web and its transformation into a fully capable application distribution platform, without the quirky hacks and framework silos of the past.

Resources Link

Elements Link
Videos Link

(al, ml, rb, jb)

Footnotes Link

  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
  10. 10
  11. 11
  12. 12
  13. 13
  14. 14
  15. 15
  16. 16
  17. 17
  18. 18
  19. 19
  20. 20
  21. 21
  22. 22
  23. 23
  24. 24
  25. 25
  26. 26
  27. 27
  28. 28
  29. 29
  30. 30
  31. 31
  32. 32
  33. 33
  34. 34
  35. 35
  36. 36
  37. 37
  38. 38
  39. 39
  40. 40
  41. 41
  42. 42
  43. 43
  44. 44
  45. 45
  46. 46
  47. 47
  48. 48
  49. 49
  50. 50
  51. 51
  52. 52
  53. 53
  54. 54

↑ Back to top Tweet itShare on Facebook

Sebastian is a web and technology enthusiast from Germany who got heavily into JavaScript in the last couple of years. Besides some freelance work his main occupation is being the technical co-founder of the start-up snapADDY. In his spare time he co-organizes the local FrankenJS JavaScript user group in Nuremberg

  1. 1

    Why Polymer, WebComponents are all about supporting native features. Why not write an article actually explaining/showing how to use it natively?

  2. 4

    None of the YouTube video links seem to be working.

    • 5

      Markus Seyfferth

      October 13, 2015 10:15 pm

      Thanks for the heads-up Bill! Very unfortunate indeed (someone decided to remove the videos), so I took out those links.

  3. 6

    Cristian Jujea

    October 13, 2015 10:22 pm

    I’m a web app product manager and an enthusiast of new web and mobile technologies. But with the headaches I get from cross-browsers compatibility issues, adaptive, responsive, interaction design, etc. etc. etc., I beg for very practical presentations of very practical technologies.

    It’s all about the end user – any developer actually works for the end user.
    Yet, User-Centered Design – which is the most practical project management type – is barely considered by developers and almost never mentioned in articles about how to apply new technologies.

    • 7

      You just don’t get it. This is so exiting, you will be able to do sliders that aren’t but :)

  4. 8

    Mike Bunce (

    October 13, 2015 11:35 pm

    We have just started using web components here at work, and they look like a great streamlined approach to include dynamic components that are shared across applications. Polymer provides a great way of having browser compatibility before browsers have formally implemented the functionality – love it!

  5. 9

    npm WARN ENOENT ENOENT: no such file or directory, open ‘/Users/saerts2013/Sites/_test/web-components/package.json’
    npm WARN EPACKAGEJSON /Users/saerts2013/Sites/_test/web-components No description
    npm WARN EPACKAGEJSON /Users/saerts2013/Sites/_test/web-components No repository field.
    npm WARN EPACKAGEJSON /Users/saerts2013/Sites/_test/web-components No README data
    npm WARN EPACKAGEJSON /Users/saerts2013/Sites/_test/web-components No license field.
    npm ERR! code 1

    ➜ web-components gulp serve
    [10:46:02] No gulpfile found

  6. 10

    In what universe is that a good thing ?
    I will spend more time learning this new kind of coding for doing the exact same thing.
    I want a google map inside a page ?
    I asset my javascript / css.
    I copy & paste my code.

    I dont have to renember your own tag, to use bower with this line etc..

    • 11

      I see your point David, and it is the pragmatic approach today and what I will continue to do for some time. But I must say I love the concept of a composable UI that rises above individual frameworks, and turns other components into blackboxes that can be added and configured right in the HTML (no-JS needed for the conventional setup of a component). A handy UI metaphor could be a google/npm/etc. search away, and tooling (think text editor with autocomplete) could be made responsible for telling me what elements and attributes are available to be set and of those which are required to be set. So learning and incorporating someone else’s blackbox into my project could be fairly painless in the near future.

      Having said all that, the idea of importing AngularJS into my project that is not using it just so that I can use a component that depends on AngularJS sounds a bit far-fetched. Frameworks will still matter.

  7. 12

    Sooo…. Beyond the overhead of shipping the polyfills across the network, there’s also the time it takes for the browser to parse and interpret the JavaScript code. Official statement is that they don’t do performance testing and optimizations. Let’s talk browser support and known issues then :)

    Browser Support:
    – IE11+
    – Chrome
    – Firefox
    – Safari 7+
    – Chrome Android
    – Mobile Safari

    Known Issues:
    – Custom element’s constructor property is unreliable
    – Contenteditable elements do not trigger MutationObserver
    – ShadowCSS: :host-context(…):host(…) doesn’t work
    – execCommand isn’t supported under Shadow DOM

    All of you – check this link before considering usage:

  8. 13

    victor castrejon

    October 14, 2015 8:43 pm

    Nice article, I really like where polymer is going.

    * BTW there is an extra = at the end of the ‘HTML templates’ link in the second paragraph

  9. 14

    Today as the online shopping grows in popularity more people are turning to online shopping for all their needs. Send Diwali Gifts to India Same Day which is filled with your good wishes. Send Deepavali Sweets to India and make your dear ones feel at the top-of-the world..

  10. 15

    What I understand is that Polymer is what I call a typical Google product.

    “Its purpose is to enable developers to work with web components (…) before the standards are finalized”
    => let’s adopt that new fancy thing before it’s mature enough.

    ““Polymer is not a framework.” The team behind it strongly emphasized this at this year’s Google I/O talk about the 1.0 release”

    “Polymer also provides some syntactic sugar that makes working with web components a bit easier.”
    So it’s not just a polyfill but also something else. But it’s not a framework.

    “One year later, the project got a big boost at Google I/O 2014, as the team announced its ambitions to drive Polymer forward by providing an extensive library of prebuilt elements”
    Still not a framework ?

    “based on the material design guidelines”
    Now it’s not just a polyfill for old browsers which don’t support a finalized standard : it’s a way to spread the Google look’n’feel with components.

    “Google web components. These web components are wrappers for Google APIs and services. For example, there is an element for Google Maps, YouTube and Google Calendar.”
    Oh even better, now it’s a framework to spread not only the Google look’n’feel across the web, but a way to promote Google services.

    What was supposed to be a purely technical polyfill turns out to be one more tool to Googlify the web. No thanks.

    • 16

      Kit Brown-Watts

      October 27, 2015 1:00 am

      The entire project is open source and no one is forcing anyone to Googlefy the web. You can use the technology to design and develop whatever you want! Obviously because the team is employed by Google, some of the initial components to be created will be Google-focused, but would you not do the exact same if you were running the team?

      Material Design is based on a great deal of human computer interaction research, everything from the line spacing to the border radius is meant to optimise readability and usability – and even then there’s absolutely nothing locking you in to using it. The entire point of Web Components and Polymer is to make it easier to encapsulate whatever look and feel you want into a standalone html element that others can just use, unlike traditional ui from frameworks.

      It’s easy to sit on the sidelines and criticise – but if you have a better vision then go ahead and do it! This is the whole point.

  11. 17

    Will take decades to all browsers support that, and will take more to text editors be able to auto complete and give you coding performance, and then another web shit will be created.

    Even HTML5 is not completely done yet. weirdo…

  12. 19

    Current browser compatibility, and any speed concerns aside, I think Polymer (and Web Components) represents a change for the better in web development.

    The “microservice” style of building components, and applications, is ideal in my mind. It’s already becoming the preferred style of developing backend api’s, why not use the same methods on the front end. When everything is decoupled (for the most part), changing a small part of the app is breeze. Polymer, for me, is sooo much nicer to use than Angular 1.x.

    There are issues though, of course. 1.0 hasn’t even been out for 6 months yet. So, people need to have a little patience with it. Eric Bidelman from the core team has a really great talk on performance from their recent Polymer Summit (all the lectures are on youtube).


↑ Back to top