Repository files navigation

Generate/register a custom element from a preact component. As of 3.0.0, this library implements the Custom Elements v1 spec.Previous versions (< 3.0.0) implemented the v0 proposal, which was only implemented in Chrome and is abandoned.

Any Preact component can be registered as a custom element simply by importingregister and calling it with your component, a tag name*, and a list of attribute names you want to observe:

importregisterfrom'preact-custom-element';constGreeting=({ name='World'})=>(<p>Hello,{name}!</p>);register(Greeting,'x-greeting',['name'],{shadow:true,mode:'open',adoptedStyleSheets:[],serializable:true});//          ^            ^           ^             ^               ^            ^                            ^//          |      HTML tag name     |       use shadow-dom        |    use adoptedStyleSheets               |//   Component definition      Observed attributes     Encapsulation mode for the shadow DOM tree     Root is serializable

* Note: as per theCustom Elements specification, the tag name must contain a hyphen.

Use the new tag name in HTML, attribute keys and values will be passed in as props:

<x-greetingname="Billy Jo"></x-greeting>

Output:

<p>Hello, Billy Jo!</p>

The Custom Elements v1 specification requires explicitly listing the names of attributes you want to observe in order to respond when their values are changed. These can be specified via the third parameter that's passed to theregister() function:

// Listen to changes to the `name` attributeregister(Greeting,'x-greeting',['name']);

If you omit the third parameter toregister(), the list of attributes to observe can be specified using a staticobservedAttributes property on your Component. This also works for the Custom Element's name, which can be specified using atagName static property:

importregisterfrom'preact-custom-element';// <x-greeting name="Bo"></x-greeting>classGreetingextendsComponent{// Register as <x-greeting>:statictagName='x-greeting';// Track these attributes:staticobservedAttributes=['name'];render({ name}){return<p>Hello,{name}!</p>;}}register(Greeting);

If noobservedAttributes are specified, they will be inferred from the keys ofpropTypes if present on the Component:

// Other option: use PropTypes:functionFullName({ first, last}){return<span>{first}{last}</span>}FullName.propTypes={first:Object,// you can use PropTypes, or thislast:Object// trick to define untyped props.};register(FullName,'full-name');

Theregister() function also accepts an optional fourth parameter, an options bag. At present, it allows you to opt-in to using shadow DOM for your custom element by setting theshadow property totrue, and if so, you can also specify the encapsulation mode withmode, which can be either'open' or'closed'. Additionally, you may mark the shadow root as being serializable with the booleanserializable property.

When using shadow DOM, you can make use of named<slot> elements in your component to forward the custom element's children into specific places in the shadow tree.

functionTextSection({ heading, content}){return(<div><h2>{heading}</h2><p>{content}</p></div>);}register(TextSelection,'text-selection',[],{shadow:true});

<text-section><spanslot="heading">My Heading</span><spanslot="content">Some content goes here.</span></text-section>

We support a number of static properties on your component that map to special behaviors of the custom element. These can be set on components like so:

classMyCustomElementextendsComponent{statictagName='my-custom-element';}functionMyOtherCustomElement(){ ...}MyOtherCustomElement.tagName='my-other-custom-element';

• tagName
  • the custom element's tag name (if not passed as the second argument toregister())
• observedAttributes
  • an array of attribute names to observe (if not passed as the third argument toregister())
• formAssociated
  • a boolean indicating whether the custom element should be form-associated

preact-shadow-dom