dom-native
Advanced tools
A Native Web Component TypeScript Optimized Utility (zero dependency, < 20kb min, < 7kb gzip)
dom-native is a minimalistic utility (<7kb gzip) embracing the DOM Native Web Components model to build simple to big applications the DOM way. #LearnWhatMatters #SimpleScaleBetter
THE DOM IS THE FRAMEWORK
YouTube tutorials: Native Web Components | Quickstart introduction
REAL DOM (i.e., No Virtual DOM): Fully embrace native DOM customElement and Web Components.
Modern (i.e., ZERO IE TAX): Only target modern browsers (e.g., Chrome, Edge Chromium, Firefox, and Safari). NO Polyfill or Shiming.
JUST A LIB NOT a framework, the Browser is the Framework (uses the native DOM customElement / webcomponent as the framework).
SMALL <7kb gzipped (< 18kb minimized) and ZERO dependency!
SIMPLE base class providing expressive lifecycle by hooking to native DOM custom elements
BaseHMLElement extends HTMLElement with .init .preDisplay .postDisplay.O(1) event binding support by fully utilizing DOM event bubbling with optional namespacing
on(containerEl, 'pointerup', '.my-div', (evt) => {
console.log('clicked')
}, {ns: 'some_namespace'});
// or can namespace "a la jquery": on(containerEl, 'pointerup.some_namespace', ...)
// ...
off(containerEl, {ns: 'some_namespace'});
import {customElement, BaseHTMLElement, onEvent} from 'dom-native';
@customElement('my-element') // shorthand for customElements.define('my-element', MyElement)
class MyElement extends BaseHTMLElement{
@onEvent('pointerup', '.big-button') // bind on this element, and call if match '.big-button'
bigButtonClick(evt) { ... }
@onDoc('pointerup', '.main-menu') // bind on document, will unbind on disconnected
mainMenuClicked(evt) { ... }
// document binding will be removed on HTMLElement detached
}
LIGHT and expressive DOM API wrappers (e.g., first(el, selector) all(el, selector))
const itemsEl = first(el, 'ul.items'); all(itemsEl,'li').map(liEl => console.log(liEl))PUB/SUB - Unleash state management with a Minimalistic pub/sub api (see below)
AGNOSTIC - NO templating included. Feel free to use template literals, handlebars, or [lit-html](https://github.com/Polymer/lit-html, or even vuejs).
IN SHORT - Simple Scales Better - Learn what matters - favor pattern over frameworks - The DOM is the Framework! - Real DOM is Back!!!
npm install dom-native
BaseHTMLElement is a simple class that extends the browser native HTMLElement and provides expressive binding mechanisms and lifecycle methods.
Here an example with some TypeScript decorators (can be used without TypeScript as well)
// main.ts
import { BaseHTMLElement, onEvent } from 'dom-native';
@customElement('hello-world') // no magic, just call customElement.register('hello-world',HelloComponent);
class HelloComponent extends BaseHTMLElement{
get name() { return this.getAttribute('name') || 'World'}
@onEvent('click', 'strong') // bind a DOM event from this element instance with a selector
onStrongClick(){
console.log(`${this.name} has been clicked`);
}
// init() - will be called only once at first connectedCallback
init(){
this.innerHTML = `Hello <strong>${this.name}</strong>`;
// or shadowDom, DocumentFragment, ....
}
// called just before the first paint.
preDisplay() {
// put here thing job that needs to be performed just before rendering and could be in init.
}
// postDisplay() - will be called at the second requestFrameAnimation (after first paint)
postDisplay(){
// some async and UI update/refresh
}
}
document.body.innerHTML = '<hello-world name="John"></hello-world>';
HTML will be:
<body><hello-world name="John">Hello <strong>John</strong></hello-world></body>
Fully based on Native Web Component (customElements) with a lightweight but powerful
BaseHTMLElement extends HTMLElementbase class with some simple and highly productive DOM APIs allowing to unparallel productivity to build simple to big Web frontends.
dom-native is designed to scale from the get-go and, therefore, fully embrace TypeScript types and makes a lightweight, expressive, and optional use of TypeScript decorators (JS decorator standard is still way off). However, all functionalities are available in pure JS as well.
dom-native BaseHTMLElement is just a base class that extends DOM native custom element class HTMLElement and add some minimalistic but expressive lifecycle methods as well as few typescript decorators (or properties for pure JS) to allow safe event bindings (i.e., which will get unbound appropriately).
// full component
import { BaseHTMLElement, onEvent, onDoc, onWin, onHub } from 'dom-native';
@customElement('full-component')
class FullComponent extends BaseHTMLElement{
//// DOM Event Bindings
// bind a method to an element DOM event with an optional selector
@onEvent('click', 'strong')
onStrongClick(){
console.log('World has been clicked');
}
// bind a method to an document DOM event with an optional selector
// Note: will be correctly unbound when this element is removed from the Document
@onDoc('click', '.logoff')
onDocumentLogoff(){
console.log('.logoff element was clicked somewhere in the document');
}
// bind a method to an window DOM event
// Note: will be correctly unbound when this element is removed from the Document
@onWin('resize')
onDocumentLogoff(){
console.log('Window was resized');
}
//// Hub Event Bindings
@onHub('HUB_NAME', 'TOPIC_1', 'LABEL_A')
onPubSubTopic1LabelAEvent(message: any, info: HubEventInfo){
console.log(`hub event message: ${message}, for topic: ${info.topic}, label: ${info.label}`);
}
//// Lifecyle Methods
// init() - will be called only once at first connectedCallback
init(){
super.init(); // best practice, call parent
this.innerHTML = 'Hello <strong>World</strong>'; // good place to set the innerHTML / appendChild
}
// preDisplay() - if defined, will be called once before first paint (i.e. first requestAnimationFrame)
preDisplay(){
console.log('before first paint');
// Note: This function can be marked async, but the first paint won't wait until resolve.
// More idiomatic to have async in postDisplay
}
// postDisplay() - if defined, will be called once after first paint, before second paint (i.e., second requestAnimationFrame)
async postDisplay(){
// good place to do some async and UI update/refresh
}
// Native custom element method on "remove".
disconnectedCallback(){
super.disconnectedCallback(); // MUST CALL for bindings (i.e., @onDoc, @onWin, @onHub) cleanup
// other cleanups as needed
}
// Native custome element method
attributeChangedCallback(attrName: string, oldVal: any, newVal: any){
// Implement when/as needed.
}
}
To fully understand BaseHTMLElement lifecycle, which is just an extension of the browser native HTMLElement one, it is essential to understand the nuances of the native HTMLElement lifecycle.
See MDN documation about custom element lifecycle callbacks
In short, there are
HTMLElement with a tag name using customElements.define('my-comp', 'MyComponent')
dom-native provides an optional convenient @customElement('my-comp') TypeScript decoratorconnectedCallback: Invoked each time the custom element is appended into a document-connected element. Each time the node is moved, this may happen before the element's contents have been fully parsed.disconnectedCallback: Invoked each time the custom element is disconnected from the document's DOM.attributeChangedCallback: Invoked each time one of the custom element's attributes is added, removed, or changed. Which attributes to notice change for is specified in a static get observedAttributes methodadoptedCallback, but it is used mostly in the iframe case, which is not common.With this in mind, here are the BaseHTMLElement extended lifecycle methods based on the native HTMLELement ones.
@customElement('my-comp') // no magic, just call a customElement.register('my-comp',MyComponent);
class MyComponent extends BaseHTMLElement{
private _data?: string;
set data(data: string){ this._data = data; }
get data(){ return this._data }
constructor(){
super(); // MUST, by DOM customElement spec
console.log('-- constructor', this.data);
}
init(){
super.init(); // not necessary, but good best practice
console.log('-- init ', this.data);
}
preDisplay(){
console.log('-- preDisplay', this.data);
}
postDisplay(){
console.log('-- postDisplay', this.data);
}
}
const el = document.createElement('my-comp');
// NOTHING is printed, the element is not added to the dom.
// DO NOT call `el.customData = 'test data'` MyComponent is not instantiated
document.body.appendChild(el);
// -- print --> '-- constructor undefined'
// -- print --> '-- init undefined'
// now 'el' has been upgraded to MyComponent instance
el.customData = 'test-data-1';
document.addEventListener('DOMContentLoaded', function () {
const el2 = document.createElement('my-comp');
// NOTE: Since called after the DOMContentLoaded, MyComponent got instantiated
// -- print --> '-- constructor undefined'
// -- print --> '-- init undefined'
el2.data = 'test-data-2'; // works, as the setter/getter got instantiated
});
// this will ask the browser to do a call back before first paint, but it will do after preDisplay, because the myComponent instance was created before
requireAnimationFrame(function(){
// -- print --> '-- preDisplay test-data-1'
// -- print --> '-- preDisplay test-data-2'
// this will ask the browser to register a callback for the upcoming paint (which is the one after this one).
// Since MyComponent had a postDisplay, it was also registered with a double requireAnimationFrame and will be called before
requireAnimationFrame(function(){
// -- print --> '-- postDisplay test-data-1'
// -- print --> '-- postDisplay test-data-2'
});
});
There is an essential detail on when the component class MyComponent gets associated with its tag my-comp, and it follows the following "element upgrade" rule.
document.createElement('my-comp') if the MyComponent associated class was defined before, then it will get immediately 'upgraded', meaning that the returned value will be of type MyComponentdocument.createElement('my-comp') the MyComponent was not defined, or if the <my-comp></my-comp> was created via a template (i.e. in a document fragment), then the MyComponent will get instantiated and associated to the tag my-comp when the element is added to the document.body DOM tree. This is important if the MyComponent has some setters/getters, as they won't be defined until after the DOM is added to the body.Here are three typical rendering scenarios:
If the component can infer its content soly from its declaration (i.e., attributes and content), then, set the innerHTML or call appendChild in the init() method. Favor this.innerHTML or one this.appendChild call (e.g., using the convenient frag('<some-html>text</some-html>) dom-native DocumentFragment builder function)
@customElement('ami-happy')
class AmIHappy extends BaseHTMLElement{
init(){
super.init(); // optional, but good best practice
const happy = this.hasAttribute('happy');
this.innerHTML = `I am ${happy ? '<strong>NOT</strong>' : ''} happy`;
}
}
const el = document.createElement('ami-happy');
document.body.appendChild(el);
// -- display --> <ami-happy>I am <strong>NOT</strong> happy</ami-happy>
If the component needs more complex data structure to render itself, but those data do not require any async, adding the component to the document to instantiate the component, and then, calling the data initializers will allow the preDisplay() to render those data before first paint.
@customElement('whos-happy')
class WhosHappy extends BaseHTMLElement{
data?: {happy: string[], not: string[]}
preDisplay(){
if (this.data){
this.innerHTML = `Happy people: ${this.happy.join(', ')} <br />
Not happy: ${this.not.join(', ')}`;
}
}
}
// create element and add it to the DOM
const el = document.createElement('whos-happy');
const whosHappyEl = document.body.appendChild(el) as WhosHappy;
whosHappyEl.data = {happy: ['John', 'Jen'], not: ['Mike']}; // <-- still before first paint, so NO flicker
// -- display --> <whos-happy>Happy people: John, Jen <br /> Not happy: Mike</whos-happy>
// Note: If we had done it at the init(), this.data would have been undefined.
When a component needs to get data asynchronously, then, async postDisplay() method is a good place to put this logic, and usually the component HTML structure gets assigned at the init() method.
@customElement('happy-message')
class HappyMessage extends BaseHTMLElement{
init(){
super.init();
this.innerHTML = '<c-ico>happy-face</c-ico><h1>loading...</h1><p>loading...</p>';
// Tips: Layout this structure appropriately with css grid/flex-box to minimize layout reshuffling on data update.
}
async postDisplay(){
const msg: {title: string, text: string} = await httpGet('/happy-message-of-the-day');
first(this,'h1')!.textContent = msg.title;
first(this,'p')!.textContent = msg.text;
// Note: Can use fancier templating, such as handlebars, lit-html, ...
}
}
const el = document.createElement('happy-message');
// -- display --> <happy-message><c-ico>happy-face</c-ico><h1>loading...</h1><p>loading...</p></happy-message>
// for first paint, and until httpGet gets resolved
// ... httpGet gets resolved
// -- display --> <happy-message><c-ico>happy-face</c-ico><h1>title from server</h1>
// <p>text form server</p></happy-message>
Note:
init()andpreDisplay()could be marked asasyncbut it would not change the lifecycle of the component as async calls will always be resolved after first paint anyway. Useinit()andpreDisplay()synchronous component initialization, and have the async work done in thepostDisplay().
constructor()v.s.init(): Many Web Component tutorials show how to create/attachShadowDomat the constructor, but callingthis.innerHTMLat the constructor is not permitted.init()get called at the firstconnectedCallbackand is a safe place to setthis.innerHTMLvalue. This allows to decouple the ShadowDom requirements from the component model, making it optional.
ShadowDom is now, since Safari supports cssParts a robust concept to follow. It allows to high component internals while exposing part of the component structure that should be visibile to the rest of the application.
See Dialog Box with Native Web Components - Part 1 and Part 2 for best practices.
import {on, off, all, first, prev, next, append, frag, attr, style } from 'dom-native';
// --------- DOM Event Helpers --------- //
// NOTE: this is the underlying API, use @on(type, [selector]) when use @customElement Native Web Component
// register a listener for this event type on one or more elements
on(els, types, listener);
// register a listener for this type and selector on one or more elements (with event.selectTarget when selector).
on(els, types, selector, listener);
// register listener with optional namespace or ctx (this)
on(els, types, selector, listener, {ns,ctx});
// unregister a listener
off(els, type, [selector,] listener)
// unregister all listeners matching a type and eventual selector.
off(els, type[, selector])
// unregister all listeners for a given namespace 'ns'
off(els, {ns})
// trigger a custom event on a given type by default
trigger(els, "MyCustomEvent", {detail: "cool", cancelable: false});
// --------- DOM Event Helpers --------- //
// --------- DOM Query Shortcuts --------- //
const els = all(el, selector); // shortcut for el.querySelectorAll but HTMLElement[]
const els = all(selector); // shortcut for document.querySelectorAll from document
const el = first(el, selector); // shortcut for el.querySelector
const el = first(selector); // shortcut for document.querySelector from document
const el = first(el); // find firstElementChild (even for fragment for browsers that do not support it)
const el = next(el[, selector]); // shortcut to find the next sibling element matching an optional selector
const el = prev(el[, selector]); // shortcut to find the previous sibling element matching an optional selector
// --------- /DOM Query Shortcuts --------- //
// --------- DOM Helpers --------- //
// Append child, refEl interpreted as parnt
const newEl = append(refEl, newEl); // standard refEl.appendChild(newEl)
const newEl = append(refEl, newEl, "first"); // Insert newEl as first element of refEl.
const newEl = append(refEl, newEl, "last"); // Here for symmetry, refEl.appendChild(newEl)
const newEl = append(refEl, newEl, "empty"); // Will empty refEl before .appendChildrefEl.appendChild(newEL)
// Append sibling, refEl interpreted as sibling
const newEl = append(refEl, newEl, "after"); // Append newEl after the refEl, use appendChild if no next sibling
const newEl = append(refEl, newEl, "before"); // Here for symmetry, refEl.parentNode.insertBefore(newEl, refEl)
// create a document fragment
const htmlFrag = html`<div>any</div><td>html</td>`; // Create document fragment (use 'template' with fallback )
// create a element
const div = elem('div'); // same as document.createElement('div')
const [div, myComp] = elem('div', 'my-comp'); // myComp could be of type MyComp if HTMLElementTagNameMap was augmented
// --------- /DOM Helpers --------- //
// --------- /CSS Helpers --------- //
// create a css Object that can be used with adoptStyleSheets
const cssObj = css`
:host{ border: solid 1px red}
`;
// on chrome will use adoptStyleSheet, on safari will create a new style element.
adoptStyleSheets(this, cssObj);
// --------- /CSS Helpers --------- //
import { hub } from 'dom-native';
// --------- Hub (pub/sub) --------- //
const myHub = hub("myHub"); // create a new named hub, and returns the named hub.
myHub.sub(topics, [labels,] handler[, opts]); // subscribe
myHub.pub(topic, [label,] data); // publish
myHub.unsub(opts.ns); // unsubscribe
// --------- /Hub (pub/sub) --------- //
push and pull provides a simple and extensible way to extract or inject data from and to a DOM subtree.
push(el, [selector,] data); // will set the data.property to the matching selector (default ".dx") elements
const data = pull(el[, selector]); // will extract the data from the matching elements (default selector ".dx")
// register custom pushers / pullers (default ones are for html form elements and simple div innerHTML)
pusher(selector, pusherFn(value){this /* dom element*/}); // pusher function set a value to a matching element
puller(selector, pullerFn(){this /* dom element*/}); // puller function returns the value from a matching element
push(el, [selector,] data);Will inject data to the matching selector (default ".dx") elements. By default, selector is ".dx".
pull(el[, selector]);Will extract the data from the matching elements (default selector ".dx")
<div id="myEl">
<fieldset>
<input class="dx" name="firstName" value="Mike">
<input class="dx" name="lastName" value="Donavan">
</fieldset>
<div>
<div class="dx dx-address-street">123 Main Street</div>
<div class="dx" data-dx="address.city">San Francisco</div>
</div>
</div>
import {first, push, pull} from 'dom-native';
const myEl = first("#myEl"); // or document.getElementById
// Extract the data from the element.
// Will first do a ".dx" select, and for each element extract the property path and value from the element.
const data = pull(myEl);
// data: {firstName: "Mike", lastName: "Donavan",
// address: {street: "123 Main Street", city: "San Francisco"}}
// Update the DOM with some data
const updateData = {address: {street: "124 Second Street"}};
push(myEl, updateData)
anim(callback, duration, ease?) is a very simple but convenient method to make animation based on requestAnimationFrame
// will call the callback, every animationFrame, with the ntime being the normalized time 0..1 for the given duration.
anim((ntime) => {
// to animation with ntime, usually * ntime
}, 200);
// Optional easing method can be passed, which should return the eased number from a normalized number (0..1)
import { easeBounceOut } from 'd3-ease';
anim((ntime) => {
// ntime is not the normalized eased time
}, 200, easeBounceOut);
dom-nativeformerly named mvdom as been rename todom-nativeas it came closer to 1.0 release. While a little longer, I felt it was punchier and more representative of the library's intent.
FAQs
A Native Web Component TypeScript Optimized Utility (zero dependency, < 20kb min, < 7kb gzip)
The npm package dom-native receives a total of 30 weekly downloads. As such, dom-native popularity was classified as not popular.
We found that dom-native demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
MCP spec updated with structured tool output, stronger OAuth 2.1 security, resource indicators, and protocol cleanups for safer, more reliable AI workflows.
Security News
More than half of CISOs now manage 10+ security areas, often with few legal safeguards and short tenures, yet continue to secure budgets and higher pay.
Security News
Libxml2’s solo maintainer drops embargoed security fixes, highlighting the burden on unpaid volunteers who keep critical open source software secure.