Wondering what’s next for npm?Check out our public roadmap! »

    @dblechoc/preact-custom-element

    4.6.0 • Public • Published

    preact-custom-element

    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.

    Usage

    Import CustomElement and call with your component a tag name *, and a list of attribute names you want to observe:

    import register from 'preact-custom-element';
    
    const Greeting = ({ name = 'World' }) => (
      <p>Hello, {name}!</p>
    );
    
    register(Greeting, 'x-greeting', ['name']);

    * Note: as per the Custom 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-greeting name="Billy Jo"></x-greeting>

    Output:

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

    Prop Names and Automatic Prop Names

    The Custom Elements V1 specification requires explictly stating the names of any attributes you want to observe. From your Preact component perspective, props could be an object with any keys at runtime, so it's not always clear which props should be accepted as attributes.

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

    import register from 'preact-custom-element';
    
    // <x-greeting name="Bo"></x-greeting>
    class Greeting extends Component {
      // Register as <x-greeting>:
      static tagName = 'x-greeting';
    
      // Track these attributes:
      static observedAttributes = ['name'];
    
      render({ name }) {
        return <p>Hello, {name}!</p>;
      }
    }
    register(Greeting);

    If no observedAttributes are specified, they will be inferred from the keys of propTypes if present on the Component:

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

    API

    register(Component, tagName, props?, options?)

    Returns a Custom Element.

    Component

    Type: object

    tagName

    Type: string

    props?

    Type: Array<string>

    options

    Type: boolean | object Default: false

    options.shadow

    Type: boolean Default: false

    Attaches a Shadow DOM instance to your Custom Element. Remember that global styles won't affect the Custom Element unless you inject (see options.injectGlobalStyles) or somehow import them from the component itself.

    options.injectStylesWithSelector

    Type: string Default: undefined Example: *

    Injects current and future style into your Custom Element. Only works if shadow: true.

    Related

    preact-shadow-dom

    Install

    npm i @dblechoc/preact-custom-element

    DownloadsWeekly Downloads

    2

    Version

    4.6.0

    License

    MIT

    Unpacked Size

    82.8 kB

    Total Files

    17

    Last publish

    Collaborators

    • avatar