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 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

This section shows you how to start an element project.

  1. Create a directory for your element project. For projects with a single element, it's common to name the project directory to match the element name.

    mkdir my-el && cd my-el

    Where my-el is the name of the element you're creating.

  2. Initialize your element. Polymer CLI asks you a few questions as it sets up your element project.

    polymer init
    
  3. Select polymer-2-element.

  4. Enter a name for your element.

    The custom elements specification requires the element name to contain a dash.

  5. Enter a description of the element.

At this point, Polymer CLI generates files and directories for your element, and installs your project's dependencies.

After the initialization process Polymer CLI generates the following files and directories.

  • bower.json. Configuration file for Bower.
  • bower_components/. Project dependencies. See Manage dependencies.
  • demo/index.html. Demo of my-el.html.
  • index.html. Automatically-generated API reference.
  • my-el.html. Element source code.
  • test/my-el_test.html. Unit tests for the element.

Polymer CLI uses Bower for dependency management.

Dependencies are stored in the bower_components directory. You should never manually alter the contents of this directory.

Use the Bower CLI to manage dependencies.

To download a dependency to bower_components/ (the --save flag saves the new dependency to bower.json):

bower install --save PolymerElements/iron-ajax

To remove the dependency from bower_components and bower.json:

bower uninstall PolymerElements/iron-ajax

When importing dependencies inside your element, you should always use a relative URL as if the dependency is a sibling of your project.

<!-- from a top-level 'some-element.html' -->
<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../paper-elements/paper-button.html">

Suppose that you ran Polymer CLI to generate an element project. Your element is named my-el. You look inside my-el.html and see that Polymer has been imported like so:

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

This path doesn't make sense. Relative to my-el.html, Polymer is actually located at bower_components/polymer/polymer.html. Whereas the HTML import above is referencing a location outside of your element project. What's going on?

Bower installs dependencies in a flat dependency tree, like so:

bower_components/
  polymer/
    polymer.html
  my-el/
    my-el.html
  other-el/
    other-el.html

This works well on the application-level. All elements are siblings, so they can all reliably import each other using relative paths like ../polymer/polymer.html. This is why Polymer CLI uses relative paths when initializing your element project.

However, one problem with this approach is that this structure does not actually match the layout in your element project. Your element project is actually laid out like so:

bower_components/
  polymer/
    polymer.html
my-el.html

Polymer CLI handles this by remapping paths. When you run polymer serve, all elements in bower_components are remapped to appear to be in sibling directories relative to my-el. The current element is served from the made-up path of /components/bower name, where bower name is the name field from your element project's bower.json file.