Use a component

This page describes how to use a LitElement component in your application. It also describes how to make sure your deployed code is browser-ready by building it for production and loading the Web Components polyfills.

Use a LitElement component

Permalink to “Use a LitElement component”

This is a general guide to using third-party LitElement components. Refer to a component's README or other documentation for specific details.

To use a LitElement component in your code:

From your project folder, install the component from npm.

npm install some-package-name

Import the component.

In a JavaScript module:

import 'some-package-name';

In an HTML page:

<script type="module">
import './path-to/some-package-name/some-component.js';
</script>

Or:

<script type="module" src="./path-to/some-package-name/some-component.js"></script>

Add the component to your application or component:

<some-component></some-component>

Develop

Permalink to “Develop”

Elements built with LitElement are published to npm as standard JavaScript modules, which all major browsers can now load.

However, LitElement and elements built with it import their dependencies using bare module specifiers (for example, import { ... } from 'module-name') instead of full paths (import {...} from '../path/to/module-name').

At the time of writing, browsers must still be provided with the full path to a standard JavaScript module in order to load it. To convert bare module specifiers to full paths, a light transform is required.

For a local server that does this automatically, try the Open Web Components ES dev server.

Build for production

Permalink to “Build for production”

To build for production, you can use a bundler such as WebPack or Rollup.

The following example configuration for Rollup resolves dependencies, converts bare module specifers to paths, and bundles the output.

rollup.config.js

import resolve from 'rollup-plugin-node-resolve';

export default {
  // If using any exports from a symlinked project, uncomment the following:
  // preserveSymlinks: true,
    input: ['src/index.js'],
    output: {
        file: 'build/index.js',
        format: 'es',
        sourcemap: true
    },
    plugins: [
    resolve()
  ]
};

See a sample build configuration for LitElement with Babel and Rollup.

Load the WebComponents polyfills

Permalink to “Load the WebComponents polyfills”

Elements built with LitElement use the Web Components set of standards, which are currently supported by all major browsers with the exception of Edge.

For compatibility with older browsers and Edge, load the Web Components polyfills.

To load the WebComponents polyfills:

From your project folder, install the @webcomponents/webcomponentsjs package:

npm install --save-dev @webcomponents/webcomponentsjs

Add the polyfills to your HTML entrypoint:

<head>
  <!--
    If you are loading es5 code you will need
    custom-elements-es5-loader to make the element work in
    es6-capable browsers.

    If you are not loading es5 code, you don't need
    custom-elements-es5-loader.
  -->
  <!--
  <script src="./path-to/custom-elements-es5-loader.js"></script>
  -->

  <!-- Load polyfills -->
  <script
    src="path-to/webcomponents-loader.js"
    defer>
  </script>

  <!-- Load component when polyfills are definitely ready -->
  <script type="module">
    // Take care of cases in which the browser runs this
    // script before it has finished running
    // webcomponents-loader.js (e.g. Firefox script execution order)
    window.WebComponents = window.WebComponents || {
      waitFor(cb){ addEventListener('WebComponentsReady', cb) }
    }

    WebComponents.waitFor(async () => {
      import('./path-to/some-element.js');
    });
  </script>
</head>
<body>
  <!-- Add the element to the page -->
  <some-element></some-element>
</body>

Ensure that node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js and node_modules/@webcomponents/webcomponentsjs/bundles/**.* are included in your build.

Do not transpile the polyfills. Bundling them is okay.

See the Webcomponentsjs documentation for more information.

Edit this page

Previous Publish a component Next Build for production