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

In this tutorial, you'll build your first custom element with Polymer 3.0. You’ll create a simple toggle button:

Sample star-shaped toggle buttons, showing pressed and unpressed state

You’ll be able to use the toggle button with simple markup like this:


In this step, you'll:

To follow this tutorial, you’ll first need to install some command line tools. See the Polymer CLI install guide for full instructions on setting up Polymer CLI and its prerequisites (Git, npm, and Node.js).

If you're comfortable that you have all the prerequisites installed, update Polymer CLI with the following command:

npm install -g polymer-cli

If you don't have the prerequisites, or you're not sure whether you have them, follow the Polymer CLI install guide.

Download the starting code for this tutorial by running the following command:

git clone

Open the project folder:

cd polymer-3-first-element

Your top-level project folder should look something like this:

The main file you’ll work with is icon-toggle.js in the top-level project folder. This file contains the definition for your custom element, which you will modify.

To install the element's dependencies and run the demo:

  1. Run npm install from the repo directory:

    npm install

    This installs the components and dependencies required to use the Polymer library and other web components.

    You will now see an extra folder named node_modules and an extra file named package-lock.json:
    • node_modules is where the project's dependencies are installed.
    • package-lock.json contains some npm-related dependency-management info.
  2. Run the Polymer development server from the root project directory:

    polymer serve --open

    You’ll see something like this:

Initial state of the demo. The demo shows three icon-toggle elements, two labeled 'statically-configured icon toggles' and one labeled 'data-bound icon toggle'. Since the icon toggles are not implemented yet, they appear as placeholder text reading 'Not much here yet'.

Keep the demo open, and move on to step 2.

Step 2: Add local DOM