Getting Started

🏅One of the four nominated projects to the "Breakthrough of the year" category of Open Source Award in 2019

Hybrids is a UI library for creating web components with strong declarative and functional approach based on plain objects and pure functions.

The simplest definition — just plain objects and pure functions - no class and this syntax
No global lifecycle — independent properties with own simplified lifecycle methods
Composition over inheritance — easy re-use, merge or split property definitions
Super fast recalculation — built-in smart cache and change detection mechanisms
Templates without external tooling — template engine based on tagged template literals
Developer tools included — Hot module replacement support for a fast and pleasant development

Getting Started

Add the hybrids npm package to your application, or use unpkg.com/hybrids CDN for direct usage in the browser.

Then, import required features and define your 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);

Finally, use your custom element in HTML document:

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

Click and play with <simple-counter> example:

ES Modules

If you target modern browsers you can use source code directly in the script tag:

<script type="module">
  import { html, define } from 'https://unpkg.com/hybrids@^4/src';
  ...
</script>

Be aware, that this mode does not provide code minification and loads all required files in separate requests.

Hot Module Replacement

HMR works out of the box, but your bundler setup may require indication that your entry point supports it. For webpack and parcel add the following code to your entry point:

// Enable HMR for development
if (process.env.NODE_ENV !== 'production') module.hot.accept();

If your entry point imports files that do not support HMR, you can place the above snippet in a module where you define a custom element. (where define method from the library is used).

Overview

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

Classes can be confusing, especially about how to use this or super() calls. They are also hard to compose. Multiple 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, the 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:

Articles

Core Concepts Series

Videos

Taste the Future with Functional Web Components (EN, ConFrontJS Conference)
Hybrids - Web Components with Simple and Functional API *(PL, WarsawJS Meetup #46)

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
<lit-counter> - render factory and lit-html for rendering in shadow DOM
<app-todos> - todo list using parent factory for state management
<tab-group> - switching tabs using children factory
<async-user> - async data in the template

Browser Support

The library requires ES2015 APIs, Shadow DOM, Custom Elements, and Template specifications. You can use hybrids in all evergreen browsers without additional preparation.

Older Browsers

The library test suite runs on IE11, but in near future only evergreen browsers will be supported starting from v5.0.0 release. However, if you still target obsolete or dead browsers (like IE11) you must add a list of required polyfills and shims.

Web Components

At first, add @webcomponents/webcomponentsjs package on top of your project:

import '@webcomponents/webcomponentsjs/webcomponents-bundle.js';

The polyfill package provides two modes in which you can use it (webcomponents-bundle.js and webcomponents-loader.js). Read more in the How to use section of the documentation.

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.

Store

Additionally, the store feature requires a fix for broken implementation of the WeakMap in IE11: