Core
Descriptions, real DOM and render()
mx builds a description tree. el.render() turns it into real DOM and keeps it in sync, touching only what changed.
Description vs real DOM#
mx.div() creates nothing. It returns a lightweight description: an array [tag, attrs, children] marked with a ._ flag. Only when you pass it into render does mx create or update DOM nodes, reusing whatever is already there.
- div
- h1
- 'Hello'
- button
- { onclick }
- 'Click'
- h1
- <div>
- <h1>Hello</h1>
- <button>Click</button>
Run it: the second render() call reuses both boxes and only rewrites the changed text node.
let { div, span } = mx;
let host = dom.div();
// Initial render
host.render(
div({ class: 'box' }, span('A')),
div({ class: 'box' }, span('B'))
);
document.body.render(host);
// Update two seconds later - re-render the same container, mx patches minimally
setTimeout(_ => host.render(
div({ class: 'box' }, span('A (updated)')),
div({ class: 'box' }, span('B'))
), 2000);Render rules#
el.render(...children) walks its arguments left to right against the element's existing children:
- Same tag at the same position: the node is reused and its attributes patched. A different tag replaces it.
- Strings and numbers become text nodes, updated in place.
null,undefinedandfalserender nothing, which makes conditional rendering straightforward.- Real DOM nodes (from
dom()) match by identity and are moved, never recreated. - Children left over from the previous render are removed.
- Plain arrays flatten into the child list, nested ones too, so
el.render(items.map(row))andel.render(...items.map(row))render the same.
You can render several children at once: el.render(head, main, footer). Matching is by position, not by key. See Position and identity for when that bites.
Core API#
| Function | Purpose | Returns |
|---|---|---|
| mx.tag(attrs?, ...children) | Create a description. Nothing touches the DOM yet. | description |
| dom.tag(attrs?, ...children) | Create a real element now, to hold or call .$() on later. | Element |
| el.render(...children) | Reconcile children into el with the rules above. | el |
| el.$attrs(attrs) | Set or remove attributes on el itself, e.g. a component host. | el |
| define(name, { $(props) }) | Register a component whose $ returns its children. | undefined |
| el.$(props) | Merge props into el.$state and re-render the component. | el |
| components | The registry: tag name to definition. | object |
Signatures and edge cases for each are in the API reference.
Attributes & prefixes#
Attributes are passed as the first argument. Use the . prefix to set DOM properties directly:
let { input, button } = mx;
let field = input({
type: 'text',
placeholder: 'Your name',
'.value': '', // .prefix sets DOM property directly
disabled: false, // false/null removes the attribute
required: true // true sets the string "true"
});
let submit = button({ type: 'submit' }, 'Send');DOM inputs care about the property value, not the attribute value. Use '.value' to set it. Same for .checked and .selectedIndex. The full syntax is on the API tab above.
Events#
Set event handlers as properties in lowercase: onclick, oninput, onchange and so on. Any function value is assigned as a property, and a handler missing from the next render is removed for you.
onClick won't work, because mx isn't React. Write onclick.
let { div, button, span } = mx;
let count = 0;
let host = dom.div();
function Counter() {
return div(
button({ onclick() { count--; host.render(Counter()); } }, '−'),
span(' ' + count + ' '),
button({ onclick() { count++; host.render(Counter()); } }, '+')
);
}
host.render(Counter());
document.body.render(host);Children#
Children can be strings, numbers, DOM nodes, or other mx.* descriptions.
let { ul, li, strong } = mx;
let list = ul(
li('One'),
li(strong('Two')),
li('Three')
);A .map() result works as a child with or without the spread:
let items = ['One', 'Two', 'Three'];
let list = dom.ul();
list.render(items.map(item => mx.li(item)));
list.render(...items.map(item => mx.li(item))); // same DOMMore in Arrays as children.
SVG namespace inheritance#
mx.svg() creates an element in the SVG namespace. Any element rendered inside an SVG parent gets the SVG namespace too: you don't need to mark <g>, <path>, <polyline> or any other nested SVG element specially.
// All children rendered inside <svg> inherit svgNS automatically
mx.svg({ viewBox: '0 0 100 100' },
mx.g({ transform: 'translate(10, 10)' },
mx.circle({ cx: 40, cy: 40, r: 30, fill: 'red' }),
mx.path({ d: 'M0 0 L80 80' })
)
)The check is based on the host element's namespaceURI. Nested render() calls re-detect the namespace from their own host, so deeply nested SVG trees work correctly.
Tag names are converted to kebab-case, so mx.foreignObject() produces <foreign-object>, which SVG ignores. The same goes for linearGradient, clipPath and the other case-sensitive SVG elements. Create them with document.createElementNS and render them as nodes. Children rendered into a foreignObject host are created back in the HTML namespace, so fo.render(mx.div(...)) displays normally. See Case-sensitive SVG elements.
Attribute syntax
The same keys work in mx.tag(), dom.tag() and $attrs().
| Syntax | Effect | Example |
|---|---|---|
| name: value | setAttribute(name, value). In render() only, value, checked and selected also set the property. | class: 'box' |
| '.name': value | Property: el[name] = value. Bypasses attributes entirely. | '.value': 'text' |
| name: null | false | removeAttribute(name). | disabled: null |
| name: true | Sets the string "true", which is right for enumerated attributes like aria-*. | required: true |
| onname: fn | Any function is assigned as a property. Removed automatically when absent from the next render(), but not by $attrs(). | onclick: fn |
mx or dom?
- Description for render() to reconcile
mx.tag()- Real element to hold a reference to
dom.tag()- Need to call .$() on it later
dom.tag()
Where $attrs() differs from render() (handlers, dual-tracked properties) is covered in Attribute prefix reference.