/lol-element

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

Primary LanguageJavaScript

lol element

npm (scoped) npm bundle size (scoped)

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

Goals

🧬 tiny API: if you need to invest time in learning something, let it be how custom elements work and not ephemeral library APIs.

😵‍💫 just enough abstractions: custom elements can be cool, but they're definitely not fancy, it is what it is.

🫒 small and lightweight: if you need to debug, start confidently with your own code, it's probably not lol.

🕳 no build step necessary: if you enjoy spending hours debugging a cryptic compile error in the terminal and hunting for that buggy dependency, we don't.

🍭 a list with random emoji in the README: checked.

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