Polymer Logo Home Guides Feature overview Try Polymer Tutorial: Build an element 1. Get set up 2. Add local DOM 3. Data binding & properties 4. React to input 5. Theming with custom properties Define elements Register an element Declare properties Instance methods Behaviors Local DOM & styling Local DOM Styling Events Handle and fire events Gesture events Data system Data system concepts Work with object and array data Observers and computed properties Data binding Helper elements Tools Tools overview Polymer CLI Document your elements Test your elements Optimize for production Publish an element Advanced tools Services What's new Release notes 1.0 Migration guide About Polymer 1.0 Build apps Overview App templates Responsive app layout Routing Localization App storage Service worker Serve your app Resources Global settings Browser compatibility API API Reference Polymer.Base array-selector custom-style dom-bind dom-if dom-repeat dom-template Polymer.Templatizer

The Polymer library is in maintenance mode. For new development, we recommend Lit.

You're viewing an older version of the Polymer library documentation. Please see Polymer 3.0 for the latest.

Contents

The 1.0 release of the Polymer core library is now out.

This release is optimized for performance and size. We're working hard on filling out the feature set. See the roadmap for more detailed timelines.

BREAKING CHANGES. This release is not compatible with the 0.5 APIs.

  • For guidance on migrating an existing 0.5 element to the 1.0 APIs, see the Migration guide.

  • For changes between 0.8 and 1.0, see the Release notes.

  • Dramatically faster startup time and runtime performance than 0.5, even in Chrome where web components are natively supported.
  • Significantly smaller payload than 0.5.
  • Completely refactored internally to be clearly layered and much less complex.
  • Brand new data-binding system that is simpler, faster, offers tighter control, and is easier to debug.
  • Brand new, lightweight shadow DOM shim called shady DOM, that lets you avoid the complexity, size, performance penalty, and invasiveness of the shadow DOM polyfill.
  • Upper bound and lower bound scoped styling, even without native shadow DOM: scoped styles don’t bleed out, and children in their own roots are protected from descendant selectors in a shadow root.

There's a lot more to 1.0—check out the Developer guide for the run-down of all the features.

As a sample of the performance difference between 0.5 and 1.0, the results from our medium-list benchmark was that Polymer 1.0 was about 3x faster on Chrome and 4x faster on Safari. The benchmark measures time to first paint for an application with a few thousand nested custom elements, with data binding.

You can find the benchmark code on GitHub. As with all benchmarks, your mileage may vary. Please try it out or create your own tests—we'd love to see them.

The following is a high-level outline of our plans for the library post-1.0.

Polymer 0.5 had a fairly robust gesture recognition system—1.0 includes basic gestures as part of the core library. More sophisticated gestures may be added in a future release as an optional components.

The shady DOM system is new to Polymer in 1.0, and radically improves performance and decreases the size of the polyfill needed to run on browsers that don’t support shadow DOM natively. The shadow DOM polyfill was optimized for correctness, though it remained impossible to perfectly polyfill shadow DOM. Shady DOM is optimized for speed.

If you're curious about the motivation behind creating shady DOM, see What is shady dom?.

In the immediate future we’ll be exploring improvements to the shady DOM system to improve interoperability with other frameworks. Shadow DOM is of course the ultimate primitive to allow for interoperability, but with shady DOM we may be able to shim such interoperability to a significant degree, focusing on common interoperability use cases.

The "theming problem"—you want to be able to easily style Polymer elements from the outside, but ::shadow and /deep/ proved to be a poor solution and are slated to be removed from the Shadow DOM spec. This release includes a robust system for ergonomic cross-scope styling inspired by and based on CSS Custom Properties.

We’ll continue to refine and improve the performance of this system. We’ll also be exploring new features around mixing in bags of properties to be redistributed to individual child elements, as well as passing arguments to mixins.

There are a few binding and template features we’ll be working on.

We’ll explore growing support for parser-challenged elements like <table> in <dom-repeat>’s.

We’ll also be adding in support for compound binding and string interpolation in bindings:

<div>Dear {{ title }} {{ lastName }},</div>

Finally, we’ll be exploring adding in a layer for using Object.observe to power the data-binding system.

We’d like to explore modularizing the shady DOM shim to be able to utilize its manipulation of scoped DOM sub-trees outside of Polymer. We’d love to be able to add this very lightweight and performant system to the broader set of web component polyfills as an alternative to the shadow DOM polyfill.

Currently Polymer uses a run-time shim for CSS custom properties to enable theming and styling elements. If you know that your styles won’t change dynamically, there is a potential performance improvement to realize by calculating all the resulting styles in advance.

We’re working on building a tool—either as an extension to vulcanize or as a separate package—that will allow you to generate all the cross-scope styling at build-time, and bump performance a bit.

The Polymer team is devoting a lot of work to tooling. There are four tools in our immediate sights to work on post-1.0:

  • Stylesheet preprocessor.
  • Polymer linter to help catch common errors that come up when developing with Polymer.
  • “Data explorer” to help visualize data flow within a Polymer application.
  • A tool to help teams manage releases for large numbers of inter-dependent elements—we certainly are in dire need of this ourselves!

Inheritance is a great feature introduced with native Custom Elements. 1.0 supports extending native HTML elements using the is attribute, but doesn’t yet support extending custom elements. There are two main reasons that this has so far landed outside the 1.0 scope:

  1. it is a more complex problem to solve than it was in 0.5 given some of the performance optimizations we have made.
  2. from building lots and lots of elements, we've found that you can get nearly 100% of the way using Polymer’s “behaviors” mechanism and composition.

That said, there are certainly some legitimate use-cases for true custom element inheritance, and we fully plan to support inheritance to the extent that it existed in 0.5.

We'll update this section as asked-questions become frequently-asked.

Not all elements have been ported to the current release, but we're porting them as fast as we can. You can find the updated elements on the all-new Element catalog.

The elements are being reorganized into more consistent product lines, including:

  • Iron elements. Basic elements that don't express a visual style. Most of the old core- elements are being renamed to iron-. Some former core- elements that implemented material design (such as core-toolbar, core-menu, core-header-panel) are being migrated to paper-.

  • Paper elements. Material design elements. All of the old paper- elements, plus a few of the old core- elements.

  • Neon elements. Animation elements.

We recognize that many projects rely on 0.5, and won’t be able to switch to the new codebase until the elements are ready. We’ll continue viewing and merging PR’s until the elements are ported. We intend for 1.0 to be the new baseline though, and to work within this high-performance, production-ready mindset going forward. Any incremental 0.5 releases, if needed, will be available in a branch.

Checkout our contributing guide for the full rundown of how to contribute. The best place for feedback is on Github, by filing an issue, adding to an existing one, or submitting a pull request. Feedback and contributions are critical to keeping Polymer successful.

Pull requests tend to be the clearest way of expressing an idea or change, but short of a pull request, as much detail as you can add around your use-case will help us and the broader community better understand the question or suggestion.

Continue on to the Polymer docs:

Try Polymer
Developer guide
Migration guide