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.

Description (mx)
  • div
    • h1
      • 'Hello'
    • button
      • { onclick }
      • 'Click'
Real DOM
  • <div>
    • <h1>Hello</h1>
    • <button>Click</button>

Run it: the second render() call reuses both boxes and only rewrites the changed text node.

JS
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, undefined and false render 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)) and el.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#

FunctionPurposeReturns
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
componentsThe 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:

JS
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');
Property vs attribute

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.

Lowercase only

onClick won't work, because mx isn't React. Write onclick.

JS
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.

JS
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:

JSFragment
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 DOM

More 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.

JS
// 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.

foreignObject and other camelCase tags

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.