hybrids

Hybrids is a UI library for creating Web Components, which favors plain objects and pure functions over class and this syntax. It provides simple and functional API for creating custom elements.

• The simplest definition — just plain objects and pure functions
• Composition over inheritance — easy re-use, merge or split property definitions
• No global lifecycle callbacks — no did* or will* and only in the independent property definition
• Super fast recalculation — built-in cache mechanism secures performance and data flow
• Templates without external tooling — template engine based on tagged template literals
• Developer tools included — Hot module replacement support for fast and pleasant development

Getting Started

Install npm package:

npm i hybrids

Then, import required features and define a custom element:

import { html, define } from 'hybrids';

export function increaseCount(host) {
  host.count += 1;
}

export const SimpleCounter = {
  count: 0,
  render: ({ count }) => html`
    <button onclick="${increaseCount}">
      Count: ${count}
    </button>
  `,
};

define('simple-counter', SimpleCounter);

👆 Click and play on ⚡StackBlitz

Finally, use your custom element in HTML:

<simple-counter count="10"></simple-counter>

Built Version

You can also use the built version from unpkg.com CDN (with window.hybrids global namespace):

<script src="https://unpkg.com/hybrids@[PUT_VERSION_HERE:x.x.x]/dist/hybrids.js"></script>

Overview

There are some common patterns among JavaScript UI libraries like class syntax, complex lifecycle or stateful architecture. What can we say about them?

Classes can be confusing, especially about how to use this, binding or super() calls. They are also hard to compose. Complex lifecycle callbacks have to be studied to understand very well. A stateful approach can open doors for difficult to maintain, imperative code. Is there any way out from all of those challenges?

After all, class syntax in JavaScript is only sugar on top of the constructors and prototypes. Because of that, we can switch the component structure to a map of properties applied to the prototype of the custom element class constructor. Lifecycle callbacks can be minimized with smart change detection and cache mechanism. Moreover, they can be implemented independently in the property scope rather than globally in the component definition.

With all of that, the code may become simple to understand, and the code is written in a declarative way. Not yet sold? You can read more in the Core Concepts section of the project documentation.

Documentation

The hybrids documentation is available at hybrids.js.org or in the docs path of the repository:

• Core Concepts
• Built-in Factories
• Template Engine
• Misc

Live Examples

• <simple-counter> - a button with counter controlled by own state
• <redux-counter> - Redux library for state management
• <react-counter> - render factory and React library for rendering in shadow DOM
• <app-todos> - todo list using parent factory for state management
• <tab-group> - switching tabs using children factory

Resources

• Taste the Future with Functional Web Components (EN, 29/10/2018 - ConFrontJS Conference)
• Hybrids - Web Components with Simple and Functional API (PL, 12/07/2018 - WarsawJS Meetup #46)

Browser Support

The library requires some of the ES2015 APIs and Shadow DOM, Custom Elements, and Template specifications. You can use hybrids in all evergreen browsers and IE11 including a list of required polyfills and shims. The easiest way is to add the following code on top of your project:

// ES2015 selected APIs polyfills loaded in IE11
// Web Components shims and polyfills loaded if needed (external packages)
import 'hybrids/shim'; 
...

Web components shims have some limitations. Especially, webcomponents/shadycss approximates CSS scoping and CSS custom properties inheritance. Read more on the known issues and custom properties shim limitations pages.

The library calls shims if needed, so direct use is not required.

License

hybrids is released under the MIT License.