Never Print Magazines

    @iconstorm/lol-element

    1.0.0-beta.1 • Public • Published

    lol element

    npm (scoped) npm bundle size (scoped)

    A JavaScript base class for creating Web Components like you know what you're doing.

    Install

    With npm (or similar):

    npm install @iconstorm/lol-element
    

    Via CDN, you can use a script tag:

    <script src="https://unpkg.com/@iconstorm/lol-element"></script>
    <script>
      const { LOL, css, html } = lol // global window.lol is made available
    </script>

    or hotlink in your ES modules:

    import { LOL, css, html } from 'https://unpkg.com/@iconstorm/lol-element?module'

    Usage

    Starting with Web Components and custom HTML elements?

    Please go read the chapter dedicated to them on the great javascript.info site. Once you're familiar with custom elements in general, you'll be enjoying LOL within minutes.

    Also the Classes chapter is a recommended read.

    No build step or transpiling is necessary. All of this just works in the browser.

    Define a component:

    import { LOL, html, css } from 'https://unpkg.com/@iconstorm/lol-element'
    
    class HelloWorld extends LOL {
      static get attributes () {
        return { name: 'with-exclamation-mark', boolean: true }
      }
    
      static get styles () {
        return css`
          span { font-size: 300%; }
        `
      }
    
      template () {
        return html`
          <span>Hello World${this.withExclamationMark ? '!' : ''}</span>
        `
      }
    }
    
    customElements.define('lol-hello-world', HelloWorld)

    Use it in your markup:

    <lol-hello-world with-exclamation-mark></lol-hello-world>

    🍩 Try this on CodePen.

    API

    The LOL class

    static shadowOptions static (getter or property)

    Define the Shadow DOM options being passed to the attachShadow() call.

    Defaults to { mode: 'open' }. Use null to not use Shadow DOM.


    static attributes static (getter or property)

    Define the element's attributes to be observed with an array of names or config objects, with following keys:

    • name string: The name of the attribute
    • reflect boolean (default: true): Whether the attribute should be reflected in a property
    • boolean boolean (default: false): Whether the attribute is a boolean type of attribute
    • read function (default: x => x): A function to process the property value being accessed
    • write function (default: x => x): A function to process the value being set in the attribute
    • fallbackValue: The value returned by the property getter when the attribute is missing

    Except for name, all options are optional.

    An attribute being reflected means that for a given foo-bar attribute, a fooBar getter/setter property will be created. So assigning a value to fooBar will set the same value to the foo-bar attribute. LOL has no observable/reactivity system, for simplicity's sake, it leverages the browser's via attributeChangedCallback.

    Attributes and props?

    Attributes live in HTML, properties belong in JavaScript objects. If the different is not clear, stack overflow is your friend. This can create some confusion. This post by Rich Harris can be interesting (scroll down to part 6).


    static styles static (getter or property)

    Define the styles for the component with CSS. The css`` template literal tag must be used.

    Example
    import { css } from '@iconstorm/lol-element'
    
    // ..
    
    static get styles() {
      return css`
        :host {
          font-size: 100%;
        }
      `
    }

    template() method

    Define the markup of the component, the html`` template literal tag must be used.

    Parameters:

    • host object: The element instance

    🔥 This method is usually called render() in many libraries and frameworks.

    Example
    import { html } from '@iconstorm/lol-element'
    
    // ..
    
    template() {
      return html`
        <p>Loren ipsum</p>
      `
    }

    changed() method

    Fires every time an attribute is added, removed, or changed. This is only an alias for attributeChangedCallback for the convenience of avoiding super.attributeChangedCallback().

    Parameters:

    • name string: The name of the attribute the changed
    • oldValue string
    • newValue string

    {propertyName}Changed() method

    An individual callback for every observed attribute, when implemented. For example, every time the foo-bar attribute changes, if there's a fooBarChanged() method defined, it will be called.

    Parameters:

    • oldValue string
    • newValue string

    emit() method

    A helper to dispatch custom events from within the element.

    Parameters:

    • eventName string: The name of the event
    • detail any: The thing being emitted, available in event.detail
    • options object: any other options for the event, defaults to { bubbles: true, cancelable: true }

    render() method

    Call this method to trigger a DOM update. You shouldn't need to implement this method.


    renderRoot property

    The DOM node where rendering happens. This is either the element's shadowRoot (when using Shadow DOM) or the host element itself (when not).

    Lifecycle callbacks

    Apart from changed() and {propertyName}Changed(), no other lifecycle callbacks are provided other than the ones offered by default in HTMLElement:

    • constructor()
    • connectedCallback()
    • attributeChangedCallback()
    • disconnectedCallback()

    See Using the lifecycle callbacks in MDN.

    ⚠️ Don't forget the `super` keyword when using these.

    If you don't call super on constructor, connectedCallback and attributeChangedCallback, things will break.

    class MyComponent extends LOL {
      constructor() {
        super()
        // ..
      }
    
      connectedCallback() {
        super.connectedCallback()
        // ..
      }
    
      attributeChangedCallback() {
        super.attributeChangedCallback()
        // ..
      }
    } 

    More info: https://javascript.info/class-inheritance#overriding-a-method

    Template syntax

    See µhtml for now.

    Named exports

    • LOL - extends LOLElement,
    • LOLElement - extends HTMLELement, render() is not implemented
    • css
    • html*
    • svg*
    import { LOL, LOLElement, css, html, svg } from '@iconstorm/lol-element'

    *implementation may vary depending on flavor (more on this soon).

    Thank-yous (prior art)

    License

    MIT

    Keywords

    none

    Install

    npm i @iconstorm/lol-element

    DownloadsWeekly Downloads

    1

    Version

    1.0.0-beta.1

    License

    MIT

    Unpacked Size

    130 kB

    Total Files

    11

    Last publish

    Collaborators

    • r3l6
    • acstll
    • tim.zeidler