CalDOM JS

An agnostic, reactive & minimalist (3kb) JavaScript UI library with direct access to native DOM.

Just ~

0.04x

Slower than Vanilla JS

at unit level

Loads ~

925%

faster than React

at initialization

Achieve near

Native

performant DOM updates

View benchmark results against Vanilla JS, Vue JS, React JS, jQuery & more.

Instead of pulling you into a library-specific magical world, CalDOM let you fully access the DOM directly while keeping the reactivity.

A 2-in-1 virtual-DOM & no-virtual-DOM approach if you will.

So you could take full advantage of native APIs & mix it with other libraries to gain superior performance & flexibility in the development process.

Zero tooling, zero dependencies, zero new syntax, just pure JS.

Why CalDOM?

This was a lightweight jQuery alternative I made myself years ago & kept on improving it slowly. Also, I wanted to stay close to the native DOM API & vanilla JavaScript. Looking back, it paid really well. Then React & Vue JS happened.

In my opinion, the reactive UI approach bought a huge productivity improvement from the perspective of the developer. Also, it enabled a lot of beginner developers to navigate the programming landscape more easily.

However, this shift also moved people away from the core stuff that’s happening under the hood. As a result, sometimes we have to struggle a lot to find solutions within the library’s limits, which are sometimes hilariously dead simple & performant to implement with native APIs.

CalDOM tries to solve this by being 100% interoperable with the native DOM. I hope this will be helpful for developers with similar requirements.

Hello World

Use it as a chainable DOM traverser and a manipulator, a lightweight jQuery alternative.

We use _ (underscore) to access CalDOM.

_("#output-1")
    .append(
        _("+h1").text("Hello World!")
    );

//Short append
_( "#output-1", _("+p", "This is CalDOM.") );

Hello World - Reactive

Build reactive components. Use it as a lightweight React JS/Vue JS alternative.

Not using classes, similar to React Hooks, but simpler.

let app = _().react(
    {},
    {
        render: state =>
            _( "+h1", `Hello ${state.name}` ) //This is XSS safe
    }
)

_("#output-2", app );

//Edit below line to update state
app.state.name = "World Reactively 💥";

Hello World - Reactive (ES6)

Also works as an extended ES6 class.

class HelloWorld extends _.Component{
 
    constructor(state){
        super();
   
        this.react(state);
    }
 
    render(state){
        return _("+div", [ //Can pass children as an array too
            _( "+h1", "Hello " + state.name ),
            
            _( "+p", ["The time is: ", state.time] )
        ]);
    }

    tick(){
        this.state.time = new Date().toTimeString().substr(0, 8);
    }

    didMount(){
        setInterval( () => this.tick(), 1000);
    }
 
}

let app = new HelloWorld( { name: "World!", time: "" } );

_("#output-3", app);

Reactive Native DOM Elements

Native DOM Node is a first-class citizen. Also, a CalDOM instance is just a wrapper around them.

This agnostic interoperability allows for an infinite amount of powerful integrations.

let app = _().react(
    {},
    {
        render: state =>{
            let div = document.createElement("div");

            let heading = document.createElement("h1");
            heading.textContent = `I'm a reactive ${state.name}`;

            div.appendChild(heading);

            //.elem gives you the direct Element
            div.appendChild( _("+h2", "💥💥💥").elem ) 

            return div;
        }
    }
)

_("#output-3-1", app );

app.state.name = "native DOM Element. 🙀";

Make existing HTML reactive

Not a fan of rendering & virtual-DOM thingies? Use CalDOM to update() pre-defined HTML content reactively.

CalDOM's API is inspired by jQuery.

let person_one = _("#person-1").react(
    {},

    {
        update: function(state, person){
            person.find(".name").text( state.name );
            person.find(".age").text( state.age );
        }
    }
)

//CalDOM batches these 2 state updates to only render once.
person_one.state.name = "Jane Doe";
person_one.state.age = 22;

Name:

Age:

Summon the power of both worlds!

Efficiently update() the DOM directly and/or proceed to virtual-DOM render if it's more suitable.

Use this.$ to hold direct DOM Node references. CalDOM keeps them in sync even when render() drastically alter the DOM structure.

class Person extends _.Component{
    constructor(){
        super();

        this.react({ name: "John", likes: ["SpongeBob"] });
    }

    render(state){
        return _("+div", [
            //Saving a reference to the direct DOM Element
            this.$.title = _( "+h1", `I'm ${state.name}` ).elem,
            
            _( "+p", "I like " + state.likes.join(" & ") )       
        ]);
    }

    update(state, person, changed_keys, changes_count){
        
        if( changes_count != 1 || !("name" in changed_keys) )
            // Too complex to update, proceed to render.
            return true;
            
        else //Update name directly using the DOM reference
            this.$.title
                .textContent = `I'm ${state.name} Directly. 🦄`;
    }
}

let user = new Person();
_("#output-4", user );

user.state.likes.push( "Hulk" ); //This is handled by render()

setTimeout( () => 
    user.state.name = "Jane" //This is handled by update()
, 1000);

There’s a lot going on here. In fact, this is the essence of CalDOM's approach.

When there is an update() function defined, CalDOM calls it instead of calling the render(). This gives us a chance to avoid expensive virtual-DOM diffing and update the DOM directly. The first render() get executed regardless and note we ask CalDOM to remember the direct H1 element using this.$.title = _(…).elem there.

The state changes are batched because it’s obviously very expensive to update the DOM on each state variable change. CalDOM waits for main thread to be idle via requestAnimationFrame and then execute render()/update() efficiently.

Hence, the update() function retrieve two additional arguments as changed_keys & changes_count. This is what state variables changed & how many changes batched since the last render. These can be used to decide whether it’s suitable to update the DOM directly. If not, we can simply proceed with the render() by returning true. Since CalDOM’s basic building box is the native DOM Element, it can switch between render() & update() seamlessly.

In above example, the name change after the 1-second timeout is handled by the update() function. Thus, it execute this.$.title .textContent = “…” directly without any expensive virtual-DOM involvement.

Use HTML to create

Similar to JSX, but with vanilla HTML & JavaScript. No compilers required.

class Person extends _.Component{

    constructor(state){
        super();

        this.react( state );
    }

    render(state){

        //Using ES6 template literals.
        //You can use regular strings as well.
        return _(`
            <div style="display: flex">
                <img src="${state.avatar}" 
                    style="border-radius: ${state.radius}px" />

                <div style="flex: 1; margin-left: 1em">
                    <h1>Name: ${state.name}</h1>
                    <h1>Age: ${state.age}</h1>
                </div>
            </div>
        `);

        //Look out for XSS, use sanitized inputs with HTML.
        //Or use XSS safe .text(), .append() or its short form: _(target, "XXS Safe Text").
    }
}

let app = new Person({ 
    name: "John Doe", 
    age: 24, 
    avatar: "images/avatar.png",
    radius: 10
});

_("#output-5", app);

Supercharge Native Web Components

CalDOM integrates seamlessly with Web Components.

Use CalDOM to create stateful & reactive Web Components. It also accepts web components as inputs.

class CustomElement extends HTMLElement{
    connectedCallback(){
        
        let title = _().react(
            { msg: "Hello World!" },
            {
                render: state => 
                    _( "+h2", state.msg )
            }
        );

        // Appending H2 as a child, keeping root intact
        // this = <custom-element>
        _( this, title );

        //Just a shortcut to access state easily
        this.state = title.state;
    }
    
    doSomething(){
        alert("Cool Eh!");
    }
}

//Registering custom element.
customElements.define("custom-element", CustomElement);

let hello = document.createElement("custom-element");
document.getElementById("output-5-1").appendChild( hello );

hello.state.msg = "I'm a Reactive, Stateful & Native Web Component. 🔥";

//Creating a new web component using CalDOM
_("#output-5-1").prepend( _("+custom-element") )

You can use these custom elements in HTML code natively as usual.

Create future-ready declarative modern web apps. Currently, native browser support for Web Components is at 95% & expected to play a primary role in future web development.🔮

<p>Click below text</p>

<custom-element onclick="doSomething()">
</custom-element>

<custom-element onclick="state.msg = 'Native Web Components are awesome! ✌️'">
</custom-element>

You can even make jQuery reactive

Basic building box of CalDOM is just native Node/Element. Thus, making it compatible with almost any DOM library on the web.

class HelloJquery extends _.Component{

    constructor(){
        super();

        this.react({ prompt: "" });
    }

    render(state){
        //Creating element & attaching click event using jQuery
        return $("<h1></h1>")
            .text( state.prompt )
            .click( () => state.prompt = "Hello from jQuery!")[0];
    }
}

let app = new HelloJquery();
_("#output-6", app);

app.state.prompt = "Click Me!"

Todo App - Non Reactive

CalDOM does not dictate your coding style or approach. It's super flexible & scalable from a single element to large nested implementations.

_("#output-7", [
    
    _("+input")
        .attr({
            id: "todo-input",
            type: "text",
            placeholder: "Type task here"
        }),

    _("+button", "Add")
        .on("click", function(){
            let task = _("#todo-input").val()[0];

            _( "#todo-list", _("+li", task ) )
        }),
    
    _("+ol").attr("id", "todo-list"),

    _("+button", "Clear")
        .on("click", function(){
            _("#todo-list li").remove();
        })
])

Todo App - Reactive

CalDOM renders a virtual-DOM and efficiently updates only changed elements in the actual DOM.

Multiple renders are batched to only run once.

class TodoApp extends _.Component{

    constructor(){
        super();

        this.react({
            items: [],
            input: ""
        });
    }

    render(state){
        return _("+div", [
            _("+input")
                .attr("placeholder", "Type task here")
                .on(
                    "change", 
                    e => state.input = e.target.value 
                ),

            _("+button", "Add")
                .on( "click", () => this.addItem() ),

            _(
                "+ol", 
                state.items.map( //Passing an array
                    item => _("+li", item)
                )
            ),
            
            _("+button", "Clear")
                .on( "click", () => this.clearAll() )            
        ])
    }

    addItem(){
        this.state.items.push( this.state.input );
    }

    clearAll(){
        this.state.items = [];
    }
}

_( "#output-8", new TodoApp() );

Todo App - Multiple Nested Reactive Components

CalDOM plays nicely with nested reusable reactive components and takes care of all DOM updates efficiently.

No matter how deeply nested, components only get re-rendered if their state is changed.

// ToDo Item Component
class ToDoItem extends _.Component{

    constructor(state){
        super();

        this.react( state );
    }

    render(state){

        //Saving a reference to li element
        return this.$.li = _("+li", state.task)
            .css({
                textDecoration: state.finished 
                    ? "line-through" 
                    : "none" 
            })
            .on( "click", () => this.onClick() )
            .elem;
    }

    update(state){

        //Directly changing CSS of the native li element
        this.$.li.style.textDecoration = 
            state.finished 
                ? "line-through" 
                : "none"
    }

    onClick(){
        this.state.finished = !this.state.finished;
    }

}

//Todo App Component
class TodoApp extends _.Component{

    constructor(){
        super();

        this.react({ items: [], input: "" });
    }

    render(state){
        return _("+div", [
            
            _("+input")
                .attr("placeholder", "Type task here")
                .on(
                    "change", 
                    e => state.input = e.target.value 
                ),

            _("+button", "Add")
                .on( "click", () => this.addItem() ),

            //Appending ToDo Item components array
            _("+ol", state.items),
            
            _("+button", "Clear Finished")
                .on( "click", () => this.clearFinished() ),

            _("+button", "Clear All")
                .css("marginLeft", "1em")
                .on( "click", () => this.clearAll() )  
        ])
    }

    addItem(){
        this.state.items.push(

            new ToDoItem({ 
                task: this.state.input,
                finished: false
            })

        );
    }

    clearAll(){
        this.state.items = [];
    }

    clearFinished(){
        for( let i = 0; i < this.state.items.length; i++ ){
            let item = this.state.items[i];

            if( item.state.finished )
                this.state.items.splice(i--, 1);
        }
    }

}

_( "#output-9", new TodoApp() );

CalDOM also runs on Node JS

Use CalDOM for server side rendering.

You can use a library like JS-DOM to implement a browser context on the server.

const { JSDOM } = require("jsdom"); 

//Set window in the global scope
window = new JSDOM().window;

const _ = require("caldom");

class ServerApp extends _.Component{

    constructor(){
        super();

        this.react( { msg: "" } );
    }

    render(state){
        return _("+p", state.msg)
            .css("color", "#199646")
    }
}

let app = new ServerApp();
_("body", app);

app.react( { msg: "Hello from NodeJS " + process.version  } );

//Saving generated HTML by the component to a file
require("fs").writeFileSync(
    "static_content.html", 
    window.document.body.innerHTML 
);

Fetching and rendering content generated in the server.

class ClientApp extends _.Component{

    constructor(){
        super();

        this.react( { static_html: null } );
    }

    render(state){
        if( !state.static_html ){
            return _("+div", "Loading...")
        }
        else{
            return _( state.static_html )
        }
    }

    //Lazy loading
    didMount(){
        fetch( "static_content.html" )
            .then( 
                response => response.text().then(
                    content => {
                        this.state.static_html = content;
                    }
                ) 
            );
    }
}

_( "#output-10", new ClientApp() );

Please note that we did not use classes to keep the examples simple without HTML & CSS. But in practice, always prefer using external CSS over directly setting CSS on elements due to obvious reasons. CalDOM has addClass(), removeClass() methods to facilitate this.

Multiple element instances, built-in XPath support & there is much more

View more examples in the Documentation