Start

Getting started

mx.js is a rendering engine under 1 KB (brotli). It turns plain JavaScript into efficient DOM updates without a build step or a virtual DOM, so the code running in the browser is the code you wrote, working on the elements you see.

<1 KBbrotliZerodeps
JSRunnablePlayground
let { div, h2, p, button } = mx;

let app = div({ class: 'app' },
    h2('Hello, mx'),
    p('This is tiny and friendly.'),
    button({ onclick: _ => alert('Clicked!') }, 'Click me')
);

document.body.render(app);

You don't need a build step or any configuration. Just include one script tag and start building.

With no compiler or transpiler in between, you can read and debug your code in devtools as you wrote it, instead of stepping through generated output and hoping the source maps line up. A toolchain upgrade can't break a build you don't have.

What is mx?#

mx.js turns plain JavaScript descriptions into real DOM and updates that DOM in place. It powers everything from 6KB marketing sites to enterprise platforms with 200+ components and 4,900+ commits.

Why mx?

  • Under 1 KB brotli - smaller than most favicons.
  • Zero dependencies - the npm package is mx alone, so there's no tree of other people's code to audit or to chase through major-version upgrades.
  • Zero build step - drop a script tag and go, and debug the same code you wrote without source maps.
  • 4 API bindings - globals with classic scripts and named exports with ESM.
  • Real DOM - no virtual DOM or scheduler in between, so elements and events behave the way the browser defines them, and what you learn carries over to any project.

Dependencies cost more over time than they save up front. Each one brings its own dependencies that nobody on your team has read, and supply-chain attacks through that chain keep getting more common. Some can't be upgraded without rewriting part of your app, and a licence change in a major version can leave you unable to upgrade at all. With mx, the only third-party code you ship is one small file you can read in full.

The name. mx began as a micro library, before it was clear what the x would turn out to be: an engine, a library, a reconciler, a helper. "Micro x" became mx, and it stuck. It's also quick to type, one key under each hand.

Install#

A script tag works everywhere. Or install from npm:

<!-- jsDelivr (recommended) -->
<script src="https://cdn.jsdelivr.net/npm/@tltdsh/mx"></script>

The classic script exposes four globals. With npm and a browser bundler, import those four names instead:

ESM
import { mx, dom, define, components } from '@tltdsh/mx';
Installing is not loading

Installing the package alone does not load it, and the ESM import creates module bindings, not window globals. Run each example here on its own, after loading the library, with the document body available.

Pinned versions, downloads and bundler setups are on the Installation page.

The 4 API bindings#

This is the entire API:

BindingReturnsUse for
mx.tag()Array (description)Inside render() - reconciled efficiently
dom.tag()HTMLElementPersistent references, calling .$() later
define(name, {})voidRegister a component
componentsobjectComponent registry lookup
JS
// mx - create descriptions (for render to reconcile)
let heading = mx.h1({ class: 'title' }, 'Hello');

// dom - create real DOM elements (persistent references)
let container = dom.div({ id: 'app' });
document.body.append(container);

// define - register a component
define('my-counter', {
    $({ count = 0 }) {
        return [
            mx.button({ onclick: () => this.$({ count: count - 1 }) }, '-'),
            mx.span(count),
            mx.button({ onclick: () => this.$({ count: count + 1 }) }, '+')
        ];
    }
});

// components - the registry
components['my-counter']  // your definition object, define() wraps $ and keeps yours as $$

mx() vs dom()#

The most important distinction in mx.js:

mx.div() returns a descriptionAn array marked as a description, so build it with mx, never by hand. Cheap to create, used inside render().
dom.div() returns a real HTMLElementUse it when you need a persistent reference.
JSRunnablePlayground
let container = dom.div();
document.body.append(container);

define('sidebar-nav', {
    $({ currentPath = '/' }) { return mx.nav('Current path: ' + currentPath); }
});

// mx.div() - description (array), for inside render()
container.render(
    mx.div({ class: 'item' }, 'Created by render')
);

// dom.div() - real element, for persistent references
let sidebar = dom('sidebar-nav', { currentPath: '/' });
document.body.append(sidebar);

// Later, update it directly:
sidebar.$({ currentPath: '/about' });
Rule of thumb

Use mx inside render() for everything. Use dom only when you need to store a reference and call .$() on it later.

render()#

el.render(...children) is the core. It reconciles children left to right against the existing DOM:

ChildWhat render() does
Same tagReuses the element, updates attributes, recurses into children
Different tagReplaces the element
String / numberCreates or updates a text node
null / falseSkipped: conditional rendering
ArrayFlattened into the child list, nested arrays too
Real DOM nodeIdentity match, for keyed lists
JSRunnablePlayground
let box = dom.div({ id: 'box' });
document.body.append(box);

// First render
box.render(
    mx.h1('Title'),
    mx.p('Paragraph one'),
    mx.p('Paragraph two')
);

// Update - only text changes, elements reused
box.render(
    mx.h1('New Title'),
    mx.p('Updated paragraph'),
    mx.p('Still here')
);

Your first component#

Register components with define() and use them with mx():

JSRunnablePlayground
define('user-card', {
    $({ name = 'Anonymous', role = 'Member', online = false }) {
        return mx.div({ class: 'card' },
            mx.div({ class: 'card-header' },
                mx.strong(name),
                online
                    ? mx.span({ class: 'badge online' }, 'online')
                    : null
            ),
            mx.p({ class: 'card-role' }, role)
        );
    }
});

// Use it
let container = dom.div();
document.body.append(container);
container.render(
    mx('user-card', { name: 'Alice', role: 'Admin', online: true }),
    mx('user-card', { name: 'Bob' })
);

State updates go through this.$({ key: value }), which merges into state and re-renders automatically.

A complete app#

A small todo app that brings together form handling, list rendering and state management.

JSRunnablePlayground
// A complete mini-app

define('todo-app', {
    $({ items = [], text = '' }) {
        return [
            mx.h3('Todos (' + items.length + ')'),
            mx.form({ onsubmit: e => {
                e.preventDefault();
                if (!text.trim()) return;
                this.$({ items: [...items, text], text: '' });
            }},
                mx.input({
                    value: text,
                    placeholder: 'Add a todo...',
                    'aria-label': 'New todo',
                    oninput: e => this.$({ text: e.target.value })
                }),
                mx.button({ type: 'submit' }, 'Add')
            ),
            mx.ul(
                ...items.map((item, i) =>
                    mx.li(
                        mx.span(item),
                        mx.button({ 'aria-label': 'Remove ' + item, onclick: _ => {
                            let next = [...items];
                            next.splice(i, 1);
                            this.$({ items: next });
                        }}, '\u00d7')
                    )
                )
            )
        ];
    }
});

document.body.render(mx('todo-app'));

Next steps#

You now know the fundamentals. Go deeper:

Elements & RenderAttributes, events, reconciliation.FormsInputs, validation, multi-step wizards.Componentsdefine, state, slots, composition.PatternsTables, virtual scroll, drag and drop.ArchitectureRouting, lazy loading, real-time data, scaling to ∞ components.