Skip to content

Building a Web Component

Dave Lockhart edited this page Feb 19, 2019 · 11 revisions

This article will cover all the different aspects of building a web component, from basic to advanced.

Before you start, make sure you've completed all the steps in Before you build it.

lego blocks


Creating a repo

First, make sure that you and your designer have decided that the component you're building should be shared. To help answer that, see: Web Components 101: Should I build a shared component?

If you decide it's not time to make it shared, your component should live within your project and not require its own repo.

Next, what type of component is it?

Design components belong in the BrightspaceUI organization and typically each have their own repo.

Application data-driven/hypermedia components belong in the BrightspaceHypermediaComponents organization, but repos are organized by entity type (user, activity, organization, etc.), so probably your repo has already been created for you.

If you're missing permissions to create a repo, reach out on the #web-platform Slack channel.

What flavour of Polymer?

Our web components are built using the Polymer library. To learn more about Polymer, see: Web Components 101: Polymer. There are three versions of Polymer and depending on where your component will be used, choosing the correct version is important.

Polymer 3

Elements in Polymer 3 look almost identical to Polymer 2, except that they're hosted inside .js files instead of .html. This is because with Polymer 3, HTML imports are out and JavaScript modules are in. Polymer 3 also shifts to NPM away from Bower as a package manager.

With the launch of Polymer 3 in May, 2018, the Polymer team announced that version 3.0 would be the last version of Polymer. Instead, they'll be focusing their efforts on LitElement, a lighter weight component wrapper. Once we get to Polymer 3, we'll re-evaluate if LitElement is the best next step.

Create a Polymer 3 element when: you are starting a new FRA, you are adding to a FRA that either is Polymer 3 or will be updated to Polymer 3 before that element is needed, or you know that your element will be needed in Brightspace Integration (BSI).

Polymer 2 Class-based

With Polymer 2 comes a cleaner JavaScript class-based syntax that closely mimics the native custom element APIs in the browser. Polymer 2 also uses the newer v1 set of polyfills, which means it can start to take advantage of native custom element and shadow DOM support in browsers.

Create a Polymer 2 element when: you know that your element only needs to work inside projects which are currently using Polymer 2. Consider helping to update that FRA to Polymer 3 rather than creating another element that will need to be updated later!

Polymer 1.x/2.x Hybrid

Hybrid elements work in projects built with either Polymer 1 or 2. They're very similar to the original Polymer 1 elements, except that they've undergone a few changes to address breaking changes in the custom element and shadow DOM APIs.

The Polymer 2.0 documentation has a good overview of hybrid elements, as well as an upgrade guide to take an existing Polymer 1 element and hybridize it.

Create a hybrid element when: you know that your element needs to work in a project that still uses Polymer 1 or 2. Consider helping to update that FRA to Polymer 3 rather than creating another element that will need to be updated later!

Quick start with polymer init generators

To instantly get all the boilerplate code and setup files you need, we've created Yeoman generators.

These automatically integrate with polymer-cli's polymer init command. So first, make sure you have polymer-cli installed globally:

npm install -g polymer-cli

For a Polymer 3 class-based element:

npm install -g generator-polymer-init-d2l-polymer-3-element

Now simply run polymer init from an empty directory and choose the appropriate template from the list.

To see and contribute to the code behind these generators:

Once the initialization code is finished, it'll run npm install to get all the necessary dependencies. That's it! Have a gander through the repo files and look in the generated README for instructions on running a local demo of the component, running tests, and so on.

From here, you can leverage the Polymer Documentation to start building out your component's functionality. Also, check out the advanced topics below for more...

Advanced Topics

Hopefully at this point you have a basic web component built and working. Now, let's dive into some more advanced topics...


Linting, unit tests and running your tests cross-browser in Sauce Labs are all covered in: Testing.


Hopefully your component will get used by hundreds of other developers in thousands of application pages and viewed by millions of users! To help those developers out, follow the simple tips in: Documenting.


By building a component that other developers are going to put into their applications, they're trusting that your component is fast. Learn how to not let them down in: Performance Tips.


Does your component render or parse dates, times or numbers? Does it display text to the user? Does it contain CSS or icons that should be mirrored in right-to-left locales? If so, you need to understand: Localization.

Wiring up to locally run a web component & BSI on your dev LMS

Do you want to see how your component will behave in the LMS without having to push to master, publish releases, and update version numbers? Check out Wiring up to locally run a web component & BSI on your dev LMS

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.