Home Start Get started Quick tour of Polymer Install Polymer 2.x Build an element 1. Get set up 2. Add local DOM 3. Data binding & properties 4. React to input 5. Theming with custom properties Build an app 1. Get set up 2. Create a new page 3. Add some elements 4. Deploy Polymer Feature overview About this release What's new in 2.0 Upgrade guide Hybrid elements Release notes Custom elements Custom element concepts Define an element Declare properties Shadow DOM & styling Shadow DOM concepts DOM templating Style shadow DOM Custom CSS properties 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 Browser support Overview Polyfills ES6 Tools Tools overview Polymer CLI CLI commands Create an element project Create an application project Document your elements Test your elements Web services polymer.json specification Node support Resources Glossary API Reference API Reference Global settings App Toolbox What's in the box? Using the Toolbox App templates Responsive app layout Routing Localization App storage Service worker Deploy Build for production Serve your app The PRPL pattern Case study Shop News Blog Community Get started Quick tour of Polymer Install Polymer 2.x
Build an element
1. Get set up 2. Add local DOM 3. Data binding & properties 4. React to input 5. Theming with custom properties
Build an app
1. Get set up 2. Create a new page 3. Add some elements 4. Deploy

Right now, the element doesn't do much. In this step, you'll give it a basic API, allowing you to configure the icon from markup, using an attribute, or from JavaScript, using a property.

First, a bit of data binding. We'll create a toggleIcon property that you can use in HTML markup, like this:

<iron-icon icon="[[toggleIcon]]"></iron-icon>

Before this will work, we'll need to declare toggleIcon as a property.

Next, add a declaration for the toggleIcon property.

Find the script tag and add the following properties to the element's class definition:

icon-toggle.html: Before

<script>
  class IconToggle extends Polymer.Element {
    static get is() {
    return "icon-toggle";
    }
    constructor() {
      super();
    }
  }
  customElements.define(IconToggle.is, IconToggle);
</script>

icon-toggle.html: After

<script>
  class IconToggle extends Polymer.Element {
    static get is() {
    return "icon-toggle";
    }
    static get properties() {
      return {
        toggleIcon: {
          type: String
        },
      }
    }
    constructor() {
      super();
    }
  }
  customElements.define(IconToggle.is, IconToggle);
</script>

Key information:

  • You must declare a property in order to use it in your HTML.
  • A simple property declaration like this one just includes the type (in this case, String).

Learn more: deserializing attributes. The declared property type affects how Polymer converts, or deserializes the attribute value (always a string value) into a JavaScript property value. The default is String, so the declaration of toggleIcon is a formality here. To learn more, see Attribute deserialization in the Polymer docs.

Now find the <iron-icon> element and change the value of the icon attribute from "polymer" to "[[toggleIcon]]".

icon-toggle.html

<!-- local DOM goes here -->
<iron-icon icon="[[toggleIcon]]">
</iron-icon>

Key information:

  • toggleIcon is a property you'll define on the toggle button element. It doesn't have a default value yet.

  • The icon="[[toggleIcon]]"assignment is a data binding. It links your element's toggleIcon property with the <iron-icon>'s icon property.

You could now use your element and set the toggleIcon property in markup or using JavaScript. If you're curious about where the new icons come from, take a look at demo-element.html in the demo folder.

You'll see lines like this:

demo-element.html—existing demo code

<icon-toggle toggle-icon="star" pressed></icon-toggle>

These lines are already in place, you don't have to add them. These lines are part of the demo you see on screen. But if you'd like to experiment, try adding a new <icon-toggle> element to the demo-element.html file. Some icon names you can try are add, menu, and settings.

Learn more: attribute and property names. You'll note that the markup above uses toggle-icon, not toggleIcon. Polymer represents camelCase property names using dash-case attribute names. To learn more, see Property name to attribute name mapping in the Polymer library docs.

The properties object also supports several more features. Add the following lines to add support for the pressed property:

icon-toggle.html: Before

<script>
  class IconToggle extends Polymer.Element {
    static get is() {
    return "icon-toggle";
    }
    static get properties() {
      return {
        toggleIcon: {
          type: String
        },
      }
    }
    constructor() {
      super();
    }
  }
  customElements.define(IconToggle.is, IconToggle);
</script>

icon-toggle.html: After

<script>
  class IconToggle extends Polymer.Element {
    static get is() {
    return "icon-toggle";
    }
    static get properties() {
      return {
        pressed: {
          type: Boolean,
          notify: true,
          reflectToAttribute: true,
          value: false
        },
        toggleIcon: {
          type: String
        },
      }
    }
    constructor() {
      super();
    }
  }
  customElements.define(IconToggle.is, IconToggle);
</script>

Key information:

  • For this more complicated property, you supply a configuration object with several fields.
  • The value specifies the property's default value.
  • The notify property tells Polymer to dispatch property change events when the property value changes. This lets the change be observed by other nodes.
  • The reflectToAttribute property tells Polymer to update the corresponding attribute when the property changes. This lets you style the element using an attribute selector, like icon-toggle[pressed].

Learn more: notify and reflectToAttribute. The notify and reflectToAttribute properties may sound similar: they both make the element's state visible to the outside world. reflectToAttribute makes the state visible in the DOM tree, so that it's visible to CSS and the querySelector methods. notify makes state changes observable outside the element, either using JavaScript event handlers or Polymer two-way data binding.

Now your element has pressed and toggleIcon properties working.

Reload the demo, and you should see star and heart icons instead of the hard-coded icon from the previous step:

Demo showing icon toggles with star and heart icons

Previous step: Add local DOM Next step: React to input