Home Start Get started 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 Quick tour 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 Resources Community Browser compatibility API Reference Polymer.Base array-selector custom-style dom-bind dom-if dom-repeat dom-template Polymer.Templatizer Global settings 2.0 Preview About Polymer 2.0 Upgrade guide App Toolbox What's in the box? Using the Toolbox App templates Responsive app layout Routing Localization App storage Service worker Serve your app Case study Shop Elements News Get started
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

Next, you'll create a simple element that displays an icon.

In this step, you'll learn about:

  • Creating a custom element using Polymer.
  • Working with local DOM.

Local DOM is the set of DOM elements managed by your element. You'll learn more about it in this section.

Local DOM? Shadow DOM? If you're familiar with shadow DOM, a new proposed web standard, local DOM is just a generic term for the same concept. Polymer's local DOM works with or without native shadow DOM support.

Edit icon-toggle.html

Open icon-toggle.html. This file contains the skeleton of a custom element.

Unlike most HTML files, this file won't display anything if you load it in a browser—it just defines a new element. The demo imports icon-toggle.html so it can use the <icon-toggle> element. As you add features to the element in the following steps, they'll show up in the demo.

Start by taking a look at the existing code:

Starting code—HTML imports

<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../iron-icon/iron-icon.html">

Key information:

  • The link rel="import" element is an HTML import, a new way of including resources in an HTML file.
  • These lines import the Polymer library and another custom element called iron-icon that you'll use later in this step.

Learn more: HTML Imports. See HTML Imports: #include for the web on HTML5Rocks.com for an in-depth discussion of HTML Imports.

Next is the definition of the element itself:

Starting code—local DOM template

<dom-module id="icon-toggle">
  <template>
    <style>
      /* local styles go here */
      :host {
        display: inline-block;
      }
    </style>
    <!-- local DOM goes here -->
    <span>Not much here yet.</span>
  </template>

Key information:

  • The <dom-module> tag wraps an element's local DOM definition. In this case, the id attribute shows that this module includes the local DOM for an element called icon-toggle.
  • The <template> actually defines the element's local DOM structure and styling. This is where you'll add markup for your custom element.
  • The <style> element inside the <template> lets you define styles that are scoped to the local DOM, so they don't affect the rest of the document.
  • The :host pseudo-class matches the custom element you're defining (in this case, the <icon-toggle>). This is the element that contains or hosts the local DOM tree.

Learn more: local DOM. Local DOM lets you add a scoped DOM tree inside an element, with local styles and markup that are decoupled from the rest of the web page. Local DOM is based on the proposed Shadow DOM specification, and works with native shadow DOM where available. To learn more, see Local DOM in the Polymer library docs.

At the end of the element definition is some JavaScript that registers the element. If the element has a <dom-module>, this script is usually placed inside the <dom-module> to keep everything together.

Starting code—element registration

  <script>
    Polymer({
      /* this is the element's prototype */
      is: 'icon-toggle'
    });
  </script>
</dom-module>

Key information:

  • The Polymer call registers the element so it's recognized by the browser.
  • The argument to the Polymer call is the new element's prototype. You'll do more with this in a later step.
  • The is property on the prototype is the new element's name. It has to match the id on the <dom-module> that contains the element's template.

Create the local DOM structure

Now that you're familiar with the basic layout of the element, add something useful to its local DOM template.

Find the <span> below the local DOM goes here comment:

icon-toggle.html—before

    <!-- local DOM goes here -->
    <span>Not much here yet.</span>
  </template>

Replace the <span> and its contents with the <iron-icon> tag below:

icon-toggle.html—after

    <!-- local DOM goes here -->
    <iron-icon icon="polymer">
    </iron-icon>
  </template>

Key information:

  • The <iron-icon> element is a custom element that renders an icon. Here it's hard-coded to use an icon named "polymer".

Style the local DOM

There are a number of new CSS selectors to work with local DOM. The icon-toggle.html file already includes a :host selector, discussed earlier, to style the top-level <icon-toggle> element.

To style the <iron-icon> element, add the following CSS inside the <style> tag after the existing content:

icon-toggle.html

    <style>
      /* local styles go here */
      :host {
        display: inline-block;
      }
      iron-icon {
        fill: rgba(0,0,0,0);
        stroke: currentcolor;
      }
      :host([pressed]) iron-icon {
        fill: currentcolor;
      }
    </style>

Key information:

  • The <iron-icon> tag uses an SVG icon. The fill and stroke properties are SVG-specific CSS properties. They set the fill color and the outline color for the icon, respectively.

  • The :host() function matches the host element if the selector inside the parentheses matches the host element. In this case, [pressed]is a standard CSS attribute selector, so this rule matches when the icon-toggle has a pressed attribute set on it.

Your custom element definition should now look like this:

icon-toggle.html

<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../iron-icon/iron-icon.html">
<dom-module id="icon-toggle">
  <template>
    <style>
      /* local DOM styles go here */
      :host {
        display: inline-block;
      }
      iron-icon {
        fill: rgba(0,0,0,0);
        stroke: currentcolor;
      }
      :host([pressed]) iron-icon {
        fill: currentcolor;
      }
    </style>
    <!-- local DOM goes here -->
    <iron-icon icon="polymer">
    </iron-icon>
  </template>
  <script>
  Polymer({
    is: 'icon-toggle',
  });
  </script>
</dom-module>

Reload the demo.

  • If you downloaded the starting code, make sure polymer serve is running and reload the demo page.

  • If you're using Plunker, your changes should show up immediately. If they don't, you may need to click Stop followed by Run to refresh the preview.

You should see the toggle buttons show up with the hard-coded icon.

Demo showing icon toggles displaying Polymer icon

You'll notice that one toggle is styled as pressed, because the pressed attribute is set in the demo. But click all you want, the button won't toggle yet; there's no code to change the pressed property.

If you don't see the new toggles, double-check your file against the code above. If you see a blank page, make sure you're clicking on the demo folder or on demo/index.html.

Previous step: Intro Next step: Use data binding and properties