Getting Started

npm version bundle size build status coverage status gitter twitter

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}
define('simple-counter', SimpleCounter);

👆 Click and play on ⚡StackBlitz

Finally, use your custom element in HTML:

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

ES Modules

If you target modern browsers and do not want to use external tooling (like webpack or parcel), you can use ES modules:

<script type="module">
// We can use "/src" here - browsers, which support modules also support ES2015
import { html, define } from '[PUT_VERSION_HERE:x.x.x]/src';

Please take to account, that it does not provide code minification and loads all required files in separate requests.

Built Version

For older browsers support you can use the built version (with window.hybrids global namespace):

<script src="[PUT_VERSION_HERE:x.x.x]/dist/hybrids.js"></script>
const { html, define } = window.hybrids;


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.


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


Core Concepts Series


Live Examples

Browser Support

Build Status

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 bundle from @webcomponents/webcomponentsjs package on top of your project:

import '@webcomponents/webcomponentsjs/webcomponents-bundle.js';
import { define, ... } from 'hybrids';

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.


hybrids is released under the MIT License.