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.
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><script src="https://unpkg.com/@tltdsh/mx"></script>npm install @tltdsh/mxThe classic script exposes four globals. With npm and a browser bundler, import those four names instead:
import { mx, dom, define, components } from '@tltdsh/mx';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:
| Binding | Returns | Use for |
|---|---|---|
| mx.tag() | Array (description) | Inside render() - reconciled efficiently |
| dom.tag() | HTMLElement | Persistent references, calling .$() later |
| define(name, {}) | void | Register a component |
| components | object | Component registry lookup |
// 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:
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' });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:
| Child | What render() does |
|---|---|
| Same tag | Reuses the element, updates attributes, recurses into children |
| Different tag | Replaces the element |
| String / number | Creates or updates a text node |
| null / false | Skipped: conditional rendering |
| Array | Flattened into the child list, nested arrays too |
| Real DOM node | Identity match, for keyed lists |
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():
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.
// 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: