Need help with heresy?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

255 Stars 16 Forks ISC License 268 Commits 2 Opened issues


React-like Custom Elements via V1 API builtin extends.

Services available


Need anything else?

Contributors list

# 10,928
255 commits
# 231,582
1 commit
# 336,992
1 commit

heresy logo heresy

Don't simulate the DOM. Be the DOM.

Social Media Photo by Alexey Zhavoronkov from a2.agencylash

WebReflection status License: ISC Build Status Greenkeeper badge

React-like Custom Elements via the V1 API built-in extends. Also available for SSR.

📣 Community Announcement

Please ask questions in the dedicated discussions repository to help the community around this project grow ♥

V1 Breaking Changes

Please be sure you understand the breaking changes landed in lighterhtml.

What is this heresy ?

This project is some sort of answer to these major trends:

  • believing you cannot have tiny APIs which are able to compete with most famous frameworks
  • believing custom elements are not cool enough to compete with such frameworks
  • believing the built-in extends of custom elements are unnecessary or not useful at all

Borrowing concepts and patterns from various libraries, heresy enables custom elements as you've never seen before:

  • declarative UI (i.e.
    ) without needing JSX transformations or tooling at all
  • locally scoped custom elements to avoid name clashing and make components reusable in any context, similarly to what you can do with React components
  • automatic component name definition passed through the optional
    to inject related styles only once per definition
  • automatic handleEvent pattern so that you can forget the unnecessary overhead of
    this.method = this.method.bind(this)
  • out of the box lifecycle events, such as
    , so that you can skip the ugly
    and other unintuitive callbacks right away (but still use them if you like)
  • out of the box
    behavior, borrowed directly from HyperHTMLElement Class
  • automatic, smart component initializer via
    that avoids all the quirks related to the initialization of custom elements and built-ins
  • an ever available
    string (you won't believe it's not always an attribute if created procedurally via a registered class)
  • automatic, lazy
    template literal tags, to populate a component's content within its optionally, locally scoped defined elements
  • provides a simplified way to target rendered nodes through the React-like
  • hooks implemented via
    render({useState, ...})
    definition. If a render has an argument, it will contain all hooks exported from augmentor. Import
    from heresy, to be able to use
    . Import
    to create custom hooks.

Custom hooks

It is possible to define your own hooks through the

defineHook(name, fn)
import {defineHook} from 'heresy';

defineHook('useCounter', ({useRef}) => () => { const counter = useRef(0); return counter.current++; });

// using the useCounter in a render const Comp = { extends: 'span', render({useCounter}) { const count = useCounter(); this.textContent = count; } };

Please note that name must be unique, so if you'd like to be sure there won't ever be conflicts, use a

instead of a string.
import {defineHook} from 'heresy';

const uso = Symbol();

defineHook(uso, ({useState}) => () => { const [current, update] = useState({}); return [current, state => { update({...current, ...state}); }]; });

const Comp = { extends: 'p', render({[uso]: useStateObject}) { const [state, update] = useStateObject(); // do something with the state } };

Usage in a nutshell

A component can be defined through both classes or raw object literals.


// as object literal const literal = { name: 'Item', extends: 'li', // will extends li constructor render() { this.htmlmy name is ${}; } };

// as class class Item extends HTMLLiElement { static name = 'Item'; // necessary if code gets transpiled static tagName = 'li'; // necessary to indicate the kind render() { this.htmlmy name is ${}; } }

While both the name and tag it represents, can be defined within the class or object, it's rather suggested to pre-define at least the tag it's going to represent, but not the name.

const literal = {
  extends: 'li',
  render() { this.html`my name is ${}`; }

// in this way it's possible to define the name only via define('Item', literal);

Alternatively, it is possible to not include name and tag, defining these via the

class Item extends HTMLLiElement {
  render() { this.html`my name is ${}`; }


  • ', Item); // OR define('MyItem:li', Item);

    Which tag ?

    The beauty and power of the built-in extends of custom elements is that you can literally represent any tag you want/need.

    However, if you'd like to simply extend a non-standard tag, you can always fall back to the

    tag kind, which will extend
    , and represent the component through its retrieved
    // either as object
    const Component = {
      extends: 'element',
      onconnected() { console.log(this.outerHTML); }

    // or as class class Component extends HTMLElement { static get tagName() { return 'element'; } onconnected() { console.log(this.outerHTML); } };

    const MyElement = heresy.define('MyElement', Component); document.body.appendChild(; // in console:

    Local components in a nutshell


    will use the global registry to define the specific declarative name, making it a good practice to namespace it (i.e.
    etc.), it is possible to define local components through the usage of
    , also aliased as

    Such a list will still pass through the registry, so that local components are fully valid custom elements that never name-clash with anything else, so that it's easier to split complex components into various sub-modules and only define their main container globally.

    The following example has been rewritten with extra details and is live on codepen.

    import {define, ref, render, html} from 'heresy';

    import {User, Pass} from './form/ui.js'; import {validate, switchPage} from './form/utils.js';

    const Form = { extends: 'form', includes: {User, Pass}, oninit() { // refs can be declared upfront or inline (see render) this.user = ref(); this.addEventListener('submit', this); }, onsubmit(event) { event.preventDefault(); if (validate(this.user.current, this.pass.current)) fetch('/log-in').then(switchPage).catch(console.error); }, // render is invoked automatically on connected // if no connected, or callback is explicitly defined render() { this.html <label>Your name: <user ref="${this.user}" name="user"></user></label> <label>Your pass: <pass ref="${ref(this," name="pass"></pass></label> ; } };

    define('SiteLogin', Form); render(document.body, html<sitelogin></sitelogin>);


    property, if present, must be a map of
    "Name": Component
    pairs, where the name could also define the tag type, like it does with

    In the previous example both

    are components extending
    , so that the tag name is not necessary, but
    {"User": User}
    , or
    {"User:button": User}
    , would eventually be valid as a local component.

    How can components be local?

    The main difference with local components is that their registry name gets polluted with a unique identifier, so that instead of

     the outcome would be 
    . The unique identifier in between (
    ) is added in cases where a component can be defined or used together with many other components, so that name clashing won't ever be an issue.

    Class and object API summary

    A similar example is live in Code Pen.

    import {define, html, render} from 'heresy';

    // classes or objects, to define components, are the same class MyButton extends HTMLButtonElement {

    // (optional) static fields to define the component/class name or tag // use define('MyButton:button', MyButton); if you want to avoid this static get name() { return 'MyButton'; } static get tagName() { return 'button'; }

    // (optional) static callback to style components (once per definition) // when there are local components, it will receive also these // in definition order static style(MyButton) { // the component could be scoped so that // to be sure the selector is the right one // always use the received component to define its styles return ${MyButton} { border: 2px solid black; } }

    // (optional) attributes that can either be true or false once accessed // reflected on the DOM as either present, or not static get booleanAttributes() { return ['checked']; }

    // (optional) store any value directly and dispatch on${name} on changes static get mappedAttributes() { return ['data']; } // if ondata(event){} is defined, event.detail will have the new value

    // (optional) native Custom Elements behavior with changes dispatched // through the onattributechanged callback static get observedAttributes() { return ['name', 'age']; }

    // (optional) event driven initialization that will happen only once // the ideal constructor substitute for any sort of one-off init // this is triggered only once the component goes live, never before * // * unless explicitly dispatched, of course oninit(event) {}

    // (optional) event driven lifecycle methods, added automatically when // no Custom Elements native methods such as connectedCallback, and others // have been explicitly set as methods onconnected(event) {} ondisconnected(event) {} onattributechanged(event = {attributeName, oldValue, newValue}) {}

    // (optional) populate this custom element content // if the signature has at least one argument, // as in render({useState, ...}), // the render will be bound automatically // with hooks capabilities render() { // this.html or this.svg are provided automatically this.htmlClick ${}!; }

    // (optional) automatically defined to trigger // thison${event.type}; handleEvent(event) {}

    // (optional) automatically defined to return this.getAttribute('is') get is () {} }

    // components can be defined both as classes or objects const Generic = {

    // both name and extends are optional // if defined via define('Name:extends', object) name: 'Generic', extends: 'element', // or div, p, etc

    // statics are defined on the derived class style(selector) {}, observedAttributes: [], booleanAttributes: [],

    // all other events supported too oninit() {} };

    // define the custom element via class (requires static name and tagName) define(MyButton);

    // or define the custom element via Component:tag define('MyButton', MyButton);

    // populate some node render(document.body, html<mybutton props="${{name:"></mybutton>);

    setTimeout(() => console.log(document.body.innerHTML)); //

    Click Magic!


    The test page uses and describes a few techniques to address all browsers, from IE9 to latest evergreen.

    The following list describes the heresy's compatibility break down:

    • IE9 and IE10 might need an
      patch, to avoid breaking on frozen template literals when passed to polyfilled WeakMaps. The patch checks for the existence of
      , hence it's completely safe for any modern browser, including IE11.
    • old Edge and all IE might need a Custom Elements polyfill upfront. In this case the famous document-register-element would be the suggested choice, since it patches built-ins right away, too.
    • Safari and WebKit have an understandable but pretty stubborn position regarding built-in elements, so that a 1K polyfill is needed in case you target Safari and WebKit.
    • you don't need a polyfill for Safari if you only extend
      , but you'll miss out 90% of the fun with programming through built-in extends

    Broader wider compatibility in a nutshell


    Alternatively, you can use this minified version to never download the Safari-only polyfill.



    Custom Elements built-ins are likely the best thing we have to build components the way we want to.

    Instead of using a non standard indirection as JSX is, we can use the power of domtagger, the hyperHTML and lighterhtml tag engine, to replace once any

     with or without nested nodes.

    The Custom Elements V1 API provides enough primitives to intercept any sort of attribute (i.e. the

    in the example), but also react to events such

    Mixed up with built-in extends in a way that any component is a real thing on the DOM instead of a facade of itself, heresy makes the creation of apps, from simple to complex, a no-brainer: define the content through

    and that's it.

    When any class is defined, it's not just necessarily a useless

    , it can be pretty much any kind of element.

    The following example is live in Code Pen. ```js import {define, ref, html, render} from 'heresy';

    // a div define(class Div extends HTMLDivElement { static get name() { return 'Div'; } static get tagName() { return 'div'; } });

    // a paragraph define('P

    ', class extends HTMLParagraphElement {});

    // a h1 define('H1

    ', class extends HTMLHeadingElement {});

    // render them all + ref example const refs = {};

    // refs can be created right away refs.div = ref();

    // or within the render render(document.body, html


    Hello there

    This is how custom elements look via heresy.

    Isn't this awesome?


    console.log(refs.h1.current); // the H1 instance/node ```

    Local components live example

    You can see the following example live. ```js // p.js - could be an object too export default class extends HTMLParagraphElement { static get tagName() { return 'p'; } oninit() { console.log(this.outerHTML); } };

    // first.js - it has a local P import P from './p.js'; export default { extends: 'div', includes: {P}, // with its own definition render() { this.html


    ; } };

    // second.js - it uses P again as local import P from './p.js'; export default { extends: 'div', includes: {P}, // with its own definition render() { this.html


    ; } };

    // index.js const {define, render, html} = heresy;

    import First from './first.js'; import Second from './second.js';

    const Div = define('Div', { extends: 'div', includes: {First, Second}, render() { this.html


    // either render(document.body, html

    ); // or even document.body.appendChild(;
    ## CSS - The components style precedence

    Components are defined once per kind, and the styles of local components are appended live before the outer component, giving it the ability to force extra styles when needed, or improve the specificity for a specific component/style when used within some other.

    ```js const Div = define('Div', { extends: 'div', includes: {First, Second}, // will receive the selectors for self and included components style(Div, First, Second) { // since outer component style is injected after // it is possible to eventually overwrite nested // components through higher priority / specificity return ${Div} { font-size: 16px; } ${Div} &gt; ${First} { padding: 0; } ${Div} ${Second} { font-weight: smaller; } ; console.log([Div, First, Second].join(', ')); }, render() { this.html<first></first><second></second>; } });

    You can see what the

    receives reading the console in this live demo.

    CSS - How to query or style all globally defined components

    Every global built-in extend will have a

    suffix to ensure both that the Custom Element can be registered, but also grant a common pattern to reach components.
    *[is$='-heresy']:hover {
      opacity: .8;

    /* ⚠ too specific: it does not work with local components */ tag[is='specific-heresy'] { display: block; }

    CSS - How to query or style local components

    When components are defined locally, there will be an incremental number between the component name and the


    Instead of addressing a specific suffix, it is instead suggested to address the known prefix.

    /* ℹ usable for both globally registered and nested components */
    tag[is^='my-button-'] {
      display: block;

    Project Showcases

    Project Achievements

    • declared elements are the instance you'd expect (no virtual, no facade)
    • declared elements can be of any kind (table, tr, select, option, ...), including element
    • declare any component within other components, breaking the limits of a single, name-clashing based registry
    • any attribute change, or node lifecycle, can be tracked via the Custom Elements V1 API (no componentDidMount and friends)
    • oninit
      , and
      events out of the box
    • handleEvent
      paradigm out of the box
    • observedAttributes
      do what everyone expects these to do
    • no redundant dom nodes, no ghost fragments, an "as clean as possible" output
    • the performance of lighterhtml, fine tuned for this specific use case
    • it's SSR (Server Side Rendering) friendly, and custom elements hydrate automatically
    • usage of
      to simplify reaching nodes after render
    • automatic
      when the method is present and no
      has been explicitly defined
    • CSS specificity is granted per each component via
      style: selector => '...'
      so that there is no need to use Shadow DOM and the heavy polyfills related to it
  • We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.