@polymer/polymer

What is @polymer/polymer?

@polymer/polymer is a library for building web components using the Polymer framework. It provides a set of features to create reusable, encapsulated HTML elements with custom behavior.

What are @polymer/polymer's main functionalities?

Define a Custom Element

This feature allows you to define a custom HTML element with specific properties and behaviors. The example shows how to create a custom element named 'my-element' with a property 'myProperty'.

class MyElement extends Polymer.Element {
  static get is() { return 'my-element'; }
  static get properties() {
    return {
      myProperty: {
        type: String,
        value: 'default value'
      }
    };
  }
}
customElements.define(MyElement.is, MyElement);

Data Binding

This feature allows you to bind data to your custom element's template. The example shows how to bind the 'myProperty' value to a div inside the custom element's template.

<dom-module id="my-element">
  <template>
    <div>{{myProperty}}</div>
  </template>
  <script>
    class MyElement extends Polymer.Element {
      static get is() { return 'my-element'; }
      static get properties() {
        return {
          myProperty: {
            type: String,
            value: 'default value'
          }
        };
      }
    }
    customElements.define(MyElement.is, MyElement);
  </script>
</dom-module>

Event Handling

This feature allows you to handle events within your custom element. The example shows how to handle a click event on a button inside the custom element's template.

<dom-module id="my-element">
  <template>
    <button on-click="handleClick">Click me</button>
  </template>
  <script>
    class MyElement extends Polymer.Element {
      static get is() { return 'my-element'; }
      handleClick() {
        console.log('Button clicked');
      }
    }
    customElements.define(MyElement.is, MyElement);
  </script>
</dom-module>

Other packages similar to @polymer/polymer

lit-element

LitElement is a simple base class for creating fast, lightweight web components. It uses lit-html to render templates and provides a reactive property system. Compared to @polymer/polymer, LitElement is more lightweight and has a smaller API surface.

stencil

Stencil is a compiler that generates Web Components and builds high-performance web apps. It combines the best concepts of the most popular frameworks into a simple build-time tool. Stencil is more focused on performance and modern web standards compared to @polymer/polymer.

skatejs

SkateJS is a library for building web components that focuses on being small and performant. It provides a simple API for defining custom elements and managing their lifecycle. SkateJS is more minimalistic and performance-oriented compared to @polymer/polymer.

README

Polymer

Polymer lets you build encapsulated, re-usable elements that work just like HTML elements, to use in building web applications.

<!-- Polyfill Web Components for older browsers -->
<script src="webcomponentsjs/webcomponents-lite.min.js"></script>

<!-- Import element -->
<link rel="import" href="google-map.html">

<!-- Use element -->
<google-map latitude="37.790" longitude="-122.390"></google-map>

Getting Started

Check out polymer-project.org for all of the library documentation, including getting started guides, tutorials, developer reference, and more.

Or if you'd just like to download the library, check out our releases page.

Polymer in 1 Minute

The Polymer library is a lightweight sugaring layer on top of the web components API's to help in building your own web components. It adds convenient features to make it easy to build complex elements:

Create and register a custom element

/**
 * A not-very-useful inline element
 */
Polymer({
    is: 'my-element'
});

<!-- use the element -->
<my-element></my-element>

Add markup to your element

<!-- define the markup that your element will use -->
<dom-module id="my-simple-namecard">
  <template>
    <div>
      Hi! My name is <span>Jane</span>
    </div>
  </template>

  <script>
    Polymer({
        is: 'my-simple-namecard'
    });
  </script>
</dom-module>

Configure properties on your element...

// Create an element that takes a property
Polymer({
    is: 'my-property-namecard',
    properties: {
      myName: {
        type: String
      }
    },
    ready: function() {
      this.textContent = 'Hi! My name is ' + this.myName;
    }
});

...and have them set using declarative attributes

<!-- using the element -->
<my-property-namecard my-name="Jim"></my-property-namecard>

Hi! My name is Jim

Bind data into your element using the familiar mustache-syntax

<!-- define markup with bindings -->
<dom-module id="my-bound-namecard">
  <template>
    <div>
      Hi! My name is <span>{{myName}}</span>
    </div>
  </template>

  <script>
    Polymer({
      is: 'my-bound-namecard',
      properties: {
        myName: {
          type: String
        }
      }
    });
  </script>
</dom-module>

<!-- using the element -->
<my-bound-namecard my-name="Josh"></my-bound-namecard>

Hi! My name is Josh

Style the internals of your element, without the style leaking out

<!-- add style to your element -->
<dom-module id="my-styled-namecard">
  <template>
    <style>
      /* This would be crazy in non webcomponents. */
      span {
        font-weight: bold;
      }
    </style>

    <div>
      Hi! My name is <span>{{myName}}</span>
    </div>
  </template>

  <script>
    Polymer({
      is: 'my-styled-namecard',
      properties: {
        myName: {
          type: String
        }
      }
    });
  </script>
</dom-module>

<!-- using the element -->
<my-styled-namecard my-name="Jesse"></my-styled-namecard>

Hi! My name is Jesse

and so much more!

Web components are an incredibly powerful new set of primitives baked into the web platform, and open up a whole new world of possibility when it comes to componentizing front-end code and easily creating powerful, immersive, app-like experiences on the web.

By being based on Web Components, elements built with Polymer are:

• Built from the platform up
• Self-contained
• Don't require an overarching framework - are interoperable across frameworks
• Re-usable

Contributing

The Polymer team loves contributions from the community! Take a look at our contributing guide for more information on how to contribute.

Communicating with the Polymer team

Beyond Github, we try to have a variety of different lines of communication available:

• Blog
• Twitter
• Google+ community
• Mailing list
• Slack channel

License

The Polymer library uses a BSD-like license available here