Guide

Quick Start

Three small programs you can run right now: a counter, a row of user cards and a todo list. They need one script tag and no build step.

Counter

A component with state.

Jump to example
User cards

Props, defaults and derived values.

Jump to example
Dynamic list

A plain function, no component.

Jump to example

The HTML shell#

Save this HTML shell, then paste one example into its final script tag.

index.htmlHTML
<!DOCTYPE html>
<html>
<head><script src="https://cdn.jsdelivr.net/npm/@tltdsh/mx"></script></head>
<body>
  <div id="demo"></div>
  <script>
    // Paste one example here.
  </script>
</body>
</html>
One example at a time

The three examples are independent. Replace that script and reload before trying the next example. Do not append the examples together.

1. A Counter#

Define a component, render it, update state with this.$().

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

document.getElementById('demo').render(mx('my-counter'));

What happened?

  • define() registers a component in mx's registry but does not call customElements.define().
  • $() receives props, merged with state.
  • this.$({ count: count + 1 }) updates state and re-renders.
Next up
Components

Props, state, lifecycle and composition.

Learn more about components

2. User Cards#

A component that takes props, computes derived values, and renders conditionally.

JSRunnablePlayground
define('user-card', {
    $({ name, role = 'Member', avatar }) {
        let initials = name.split(' ').map(w => w[0]).join('');
        return mx.div({ class: 'card', style: 'display:flex;gap:12px;align-items:center;padding:16px;border:1px solid rgba(128,128,128,.4);margin:4px 0' },
            avatar
                ? mx.img({ src: avatar, style: 'width:40px;height:40px;border-radius:50%' })
                : mx.div({ style: 'width:40px;height:40px;border-radius:50%;background:#f0a828;display:flex;align-items:center;justify-content:center;font-weight:600;color:#111' }, initials),
            mx.div(
                mx.div({ style: 'font-weight:500' }, name),
                mx.div({ style: 'font-size:13px;opacity:.75' }, role)
            )
        );
    }
});

let container = document.getElementById('demo');
container.render(
    mx('user-card', { name: 'Alice Chen', role: 'Engineer' }),
    mx('user-card', { name: 'Bob Smith', role: 'Designer' }),
    mx('user-card', { name: 'Carol Wu', role: 'PM' })
);

What happened?

Next up
Elements & rendering

How descriptions become DOM, and what render() keeps.

Learn more about rendering

3. A Dynamic List#

This one doesn't need a component, just a function that renders into a container.

JSRunnablePlayground
let items = ['Learn mx.js', 'Build something', 'Ship it'];

function renderList(target) {
    target.render(
        mx.h3('Tasks (' + items.length + ')'),
        // A form, so Enter in the field adds too.
        mx.form({ style: 'display:flex;flex-direction:row;gap:8px;margin:8px 0', onsubmit: e => {
            e.preventDefault();
            let input = target.querySelector('#new-item');
            if (!input.value.trim()) return;
            items.push(input.value);
            input.value = '';
            renderList(target);
        }},
            mx.input({ id: 'new-item', placeholder: 'New task...', 'aria-label': 'New task', style: 'flex:1;height:28px' }),
            mx.button({ type: 'submit' }, 'Add')
        ),
        mx.ul(
            ...items.map((item, i) =>
                mx.li({ style: 'display:flex;justify-content:space-between;padding:4px 0' },
                    mx.span(item),
                    mx.button({ onclick: _ => {
                        items.splice(i, 1);
                        renderList(target);
                        // Removing the bottom row takes the focused button with it.
                        if (i >= items.length) target.querySelector('#new-item').focus();
                    }, 'aria-label': 'Remove ' + item, style: 'border:none;background:none;color:var(--e1);cursor:pointer' }, '\u00d7')
                )
            )
        )
    );
}

renderList(document.getElementById('demo'));

What happened?

  • Plain functions work great for simple UI.
  • Each change updates items in place and calls renderList() again.
  • render() reuses the existing rows and updates them by position, so read Position and identity before you keep per-row state in a list.
Next up
Patterns

Lists, tables and the patterns real apps use.

Learn more about patterns

Next Steps#

TutorialBuild a contact form with toast notifications, step by step.FormsInputs, validation, multi-step wizards.ArchitectureRouting, lazy loading, scaling to full applications.