API Reference

mx(tag, attrs?, ...children)

Creates a lightweight element description (an array with ._=true). This is not a DOM node - it's a compact representation that render() will reconcile against the live DOM.

mx is a Proxy. You can call it directly or destructure tag helpers from it:

// Direct call
mx('div', { class: 'box' }, 'Hello');

// Proxy destructuring (most common)
let { div, span, button, h1 } = mx;
div({ class: 'box' }, span('Hello'));

// CamelCase auto-converts to kebab-case
mx.myComponent({ prop: 'value' });
// equivalent to: mx('my-component', { prop: 'value' })

dom(tag, attrs?, ...children)

Creates and returns an actual DOM element immediately. Same Proxy/destructuring pattern as mx, but produces live nodes instead of descriptions.

// Direct call - returns a real DOM element
let el = dom('div', { class: 'box' }, 'Hello');
document.body.appendChild(el);

// Proxy destructuring
let { div, input } = dom;
let field = input({ type: 'text', '.value': 'hello' });
document.body.appendChild(field);

// With components - calls $() and returns the element
let btn = dom('a-button', { label: 'Click me' });

define(name, methods)

Registers a component tag name. When mx creates an element with that tag, it copies the methods onto the element instance. The special $ method is the render function.

define('my-counter', {
  $({ count = 0 }) {
    let { div, button, span } = mx;
    return div(
      button({ onclick: () => this.$({ count: count + 1 }) }, '+'),
      span(count)
    );
  }
});

// Usage with mx()
document.body.render(
  mx.myCounter({ count: 5 })
);

// Usage with dom()
let counter = dom('my-counter', { count: 5 });

The $ function

The $ method is the core of every component. It receives a state object (merged from attributes and this.$state) and returns an array of children to render.

define('greeting', {
  $({ name = 'World' }) {
    // this = the DOM element
    // this.$state = persistent state across renders
    // Return children (array or single mx array)
    return mx.div(
      mx.h2('Hello, ' + name),
      mx.p('Welcome to mx.js')
    );
  }
});

this.$state

A plain object that persists across renders. Every $ call runs Object.assign(this.$state, props) before your function, so $state always reflects the most recently merged props. You rarely reference it directly - destructure from the argument and call this.$({...}) to update:

$({ count = 0 }) {
    // count is destructured from $state after the merge.
    // Default (= 0) applies on first render when nothing has been set.
    return mx.button({
        onclick: () => this.$({ count: count + 1 })
    }, count);
}

For the rare case of seeding a value that can't come as a prop (stable IDs, component-owned Sets) and needs to be externally readable, this.$state.x ??= defaultValue is available. For internal-only state (intervals, caches, DOM refs) use this._x instead - see $state vs this._property.

this.$attrs(attrs)

Efficiently sets multiple attributes/properties on the element. Supports the same prefix system as render(). Returns this for chaining.

let el = dom.input();
el.$attrs({
  type: 'text',
  '.value': 'hello',
  class: 'form-input',
  placeholder: 'Type here...'
});

this.render(...children)

Available on every element (added to Element.prototype). Inside components, the wrapper calls render() with whatever $ returns.

Element.prototype.render(...nodes)

The core reconciliation method. Accepts any mix of mx arrays (._=true), DOM nodes, strings, and numbers. Falsy values (null, undefined, false) are skipped.

let { div, span } = mx;
let container = document.getElementById('app');

// Initial render
container.render(
  div({ class: 'box' }, span('Hello')),
  div({ class: 'box' }, span('World'))
);

// Update - mx diffs and patches minimally
container.render(
  div({ class: 'box active' }, span('Hello!')),
  div({ class: 'box' }, span('World'))
);

Behavior

• Walks children left-to-right, reusing existing DOM nodes by tag name.
• If a child is a component (has $), delegates rendering to that component.
• Text nodes are updated in place when content changes.
• Excess old children are removed. New children are appended.
• Returns this for chaining.

Element.prototype.$attrs(attrs)

Sets attributes and properties on an element using the same prefix system as render() - but a plain key is always setAttribute; the checked/selected/value property writes belong to render() alone. dom() applies its attrs through $attrs, so the same holds for dom.select({ value }). Returns this for chaining.

el.$attrs({
  class: 'active',           // setAttribute('class', 'active')
  '.value': 'hello',         // el.value = 'hello'
  '.checked': true,          // el.checked = true
  onclick: fn,               // el.onclick = fn (functions are assigned as properties)
  disabled: null,             // el.removeAttribute('disabled')
  hidden: false               // el.removeAttribute('hidden')
});

Attribute Prefix Reference

The attribute system recognizes these patterns when setting attributes in both render() and $attrs() (and therefore dom(), which goes through $attrs). The dual-tracking of checked/selected/value noted below is render() only - $attrs and dom() do setAttribute/removeAttribute and nothing else for a plain key - see Differences from render():

components

A plain object that serves as the global component registry. When you call define(name, methods), the methods are stored in components[name]. You can check if a component is registered:

if (!components['my-widget']) {
  define('my-widget', { $() { ... } });
}

Quick Reference