Use a component

This documentation is a work in progress. It describes prerelease software, and is subject to change.

Use a LitElement component
Build for production
Load the WebComponents polyfills

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

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:

Install the component from npm.
```
npm install --save 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 the page via markup:
```
<some-component></some-component>
```

Build for production

LitElement is published on npm using JavaScript Modules. This means it can take advantage of the standard native JavaScript module loader available in all current major browsers.

You will need a light transform to resolve LitElement’s npm dependencies. This can be done with a bundler such as WebPack or Rollup.

The following example configuration for Rollup resolves modules and dependencies, 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

To load the WebComponents polyfills:

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.