This repository has been archived by the owner. It is now read-only.
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
110 lines (77 sloc) 2.52 KB
title description layout weight
Web Components
Using metal components as web components (custom elements).

Web Components

Metal components are generally invoked in one of three ways:

  • JavaScript
new metal.MyComponent({
	title: 'Hello, World!'
}, '#element');
  • Soy
{call MyComponent.render}
	{param title: "Hello, World!" /}
  • JSX
<MyComponent title="Hello, World" />

However, with the help of the metal-web-component package, Metal components can be invoked as Custom Elements in plain HTML.

<my-component title="Hello, World"></my-component>


First you must install the metal-web-component package:

npm i --save metal-web-component

Currently, web components don't work on every browser, so a polyfill must be used. Include the webcomponents-lite polyfill if you intend to use web components on Firefox, Edge, or IE11.

Define web components

This package exposes a single helper function that can be used to wrap any Metal component in a web component. It receives two arguments: the tag name you want the web component to receive, and the constructor of the Metal component:

import JSXComponent from 'metal-jsx';
import defineWebComponent from 'metal-web-component';

class MyComponent extends JSXComponent {
	render() {
		return <h1>{this.props.message}</h1>

MyComponent.PROPS = {
	message: {
		value: ''

defineWebComponent('my-component', MyComponent);

Now that the web component is defined, it can be invoked in plain html:

<my-component message="This is a web component"></my-component>

This results in the following HTML on the page:

<h1>This is a web component</h1>

If you would like the component's markup to be rendered using the Shadow DOM, simply set the useshadowdom attribute to true when calling the web component:

<my-component message="This is a web component" useshadowdom="true"></my-component>

This means that any styling on the page will not cascade to your component's markup. See MDN's documentation for more info.