WildflowerJS Logo WildflowerJS

WildflowerJS Reactive JS, No BS*

A no-build reactive JavaScript framework, rooted in the web platform.
No build step. No dependencies. No lock-in.

<script src="wildflower.min.js"></script> ...and start building.

Back to Basics

The code you write is 100% web standard code. HTML stays HTML. JavaScript stays JavaScript. CSS stays CSS. No JSX, no templating language, no custom syntax to learn. If you know the web platform, you already know how to use this.

WildflowerJS extends the web platform. It doesn't replace it.

Your Development Simplified

Because you develop with 100% web standards, every tool in your existing chain already understands the code: IDE, browser DevTools, linter, formatter, screen reader, SEO crawler. Nothing to install, no custom file types, no sourcemaps. Save the file, refresh, and your change is live.

Just be a web developer.

Batteries Included: One Mental Model

Router, SSR, stores, computed properties, two-way binding, event modifiers, data pools, and TypeScript types, all built in, all speaking the same language. Learn data-bind once and you know binding everywhere: lists, pools, stores, forms. There's no five-library stack to keep in sync.

One script tag. Everything you need.

<div data-component="counter">
  <span data-bind="count"></span>
  <button data-action="increment">
    +1
  </button>
</div>

<script>
wildflower.component('counter', {
  state: { count: 0 },
  increment() { this.count++ }
})
</script>

How It Works

data-bind connects state to the DOM.

data-action connects events to methods.

this.count++ triggers a precise DOM update.

Mutate state. The DOM updates.

Two Reactivity Modes

data-list for automatic reactivity: mutate state, DOM updates. data-pool for explicit control: plain objects, zero proxy overhead, you say what changed.

Same template syntax. Different performance profile. From interactive forms to per-frame particle systems. You choose the right tradeoff for the job.

Try it. Right-click, inspect this demo. Every dot is a real DOM element.

See full demo →

Get Started View Demos
* Build Step

Zero Toolchain

Modern frameworks ask you to install a compiler, a bundler, a package manager, hundreds of fragile transitive dependencies, and a framework-specific file format, before you write a single line of your application.

WildflowerJS was built starting from a single principle: no build step, no tooling. Ever.

WildflowerJS asks you to add a script tag.

There's no CLI scaffolding step, no config files, no .vue/.jsx/.svelte source format. You don't debug through sourcemaps or wait on a build pipeline. Your project has zero dependencies.

Performance isn't a tradeoff. Build steps optimize bundle delivery, not the runtime work that follows it. WildflowerJS writes directly to the DOM, with no virtual DOM or reconciliation pass between state change and update, so it doesn't need a build step to be fast.

The framework is full-featured without the toolchain: router, SSR, stores, computed properties, transitions, pools. You don't need a toolchain to use any of it.

my-app/
  index.html
  app.js
  style.css
  wildflower.min.js

That's the entire project. No package.json.
No node_modules. No config files. Ship it.

Zero Install. Zero Attack Surface.

Every dependency you install is trust extended to a maintainer you've never met, running scripts on your dev machine and in your CI. A typical React + Vite + UI‑lib setup pulls in 300+ transitive packages before you write a feature.

Each one is a potential intrusion vector. NPM worms, OAuth chains compromising deploy platforms, postinstall hijacking: the supply chain is now where production code gets compromised, not the deploy. And signing isn't a backstop: Mini Shai‑Hulud (May 2026) compromised 170+ packages whose malicious versions carried valid SLSA Build Level 3 provenance, because the attestation came from build infrastructure the worm had already taken over.

WildflowerJS users don't have this attack surface, by construction. There is no npm install, no postinstall script, no transitive package graph. The framework is one file you copy or pin by hash.

As of v1.1, the same holds for building the framework itself. WildflowerJS bundles with a vendored rollup and terser pipeline pulled as three SHA‑512‑pinned tarballs: no npm install, no transitive packages, no postinstall scripts in the build path. The entire toolchain is three files you verify by hash.

Zero dependencies is the absence of a problem the rest of the industry has not properly addressed.

A typical React/Vue project:

  npm install
  ├── hundreds of packages
  ├── from hundreds of maintainers
  ├── postinstall scripts run on install
  └── tens to hundreds of MB of transitive code

WildflowerJS:

  <script src="wildflower.min.js"></script>
  └── 1 file.
      No transitive dependencies.

Zero Lock-in

WildflowerJS works with the DOM, not instead of it. There's no virtual DOM intercepting your code and no compiler rewriting your markup. The render cycle is yours.

That means Leaflet, DataTables, Chart.js, D3, Three.js, any library that touches the DOM, just works. No wrapper packages or framework-specific escape hatches required. Drop in a script tag and use it.

Because your code is standard HTML and JavaScript, you're never locked in. Your skills transfer and your code is more portable. If you outgrow the framework, your knowledge doesn't expire.

This also means your "ecosystem" is all of the world of vanilla JS. Without compromises or hacks.

<!-- Use any library directly -->
<div data-component="map-view">
  <div id="map" style="height: 400px"></div>
</div>
wildflower.component('map-view', {
  state: { lat: 51.505, lng: -0.09 },
  init() {
    // Leaflet works as-is. No wrappers.
    this._map = L.map('map')
      .setView([this.lat, this.lng], 13);
    L.tileLayer('https://{s}.tile.osm.org'
      + '/{z}/{x}/{y}.png').addTo(this._map);
  }
})

Precise Reactivity

When you write this.count++, WildflowerJS updates the single DOM node bound to count. Nothing else is touched. There's no tree diffing or reconciliation pass to figure that out.

This isn't a tradeoff. You get fine-grained updates and a simple mental model. Change a property, the bound element updates. That's the entire reactivity model.

Other frameworks ask you to learn signals, accessors, memos, effects, and subscription lifecycles to achieve what WildflowerJS does with a property assignment.

wildflower.component('dashboard', {
  state: {
    users: 1420,
    status: 'healthy'
  },
  computed: {
    summary() {
      return this.users + ' users, ' + this.status;
    }
  },
  refresh() {
    this.users = 1421;
    // Only the elements bound to 'users'
    // and 'summary' update. Everything
    // else on the page is untouched.
  }
})

One Reactivity Model. Everywhere.

Components, Stores, and Plugins all share the same reactive foundation. State, computed properties, and methods work identically no matter where they live. Learn it once, it works the same way in a UI component, a global store, or a framework plugin.

Other frameworks make you learn a different system for each layer. React components use hooks, but stores need Redux or Zustand, which are completely different APIs. Vue components use reactive data, but Pinia stores have their own patterns. Every layer is a new mental model.

In WildflowerJS, there's one model. A store is a component without a template. A plugin is an entity that extends the framework itself, adding directives, lifecycle hooks, and services. The same this.count++ triggers the same reactivity everywhere.

This unlocks patterns other frameworks can't express. A store can run headless physics simulations with tick(), feeding data into a component that renders it through a pool, all using the same reactive primitives, no glue code required.

// Component: reactive UI
wildflower.component('cart', {
  state: { items: [] },
  computed: {
    total() { return this.items.length; }
  }
})

// Store: global shared state
wildflower.store('user', {
  state: { name: '', role: 'guest' },
  computed: {
    isAdmin() { return this.role === 'admin'; }
  }
})

// Plugin: extends the framework
wildflower.plugin({
  name: 'notifications',
  state: { items: [], unreadCount: 0 },
  computed: {
    hasUnread() { return this.unreadCount > 0; }
  },
  add(msg) { this.items.push(msg); this.unreadCount++; }
})
// Access globally: wildflower.$notifications.add(...)

// Same state. Same computed. Same methods.

Data Pools

Every framework wraps collection items in reactive proxies, whether the item needs it or not. WildflowerJS gives you a choice: data-list for push reactivity (automatic), data-pool for pull reactivity (explicit control, zero proxy overhead).

Pools render plain objects with the same template syntax as lists. Mutate the object, call markDirty(), and only that item updates. Full CRUD, selection, bulk operations, all faster than the push-reactive path.

And because pools use pull-based rendering, they scale to simulations, games, particle systems, and data visualizations at native frame rate. Use cases that would choke a virtual DOM. No other framework has anything like this.

<div data-component="user-table">
  <tbody data-pool="users" data-key="id">
    <template>
      <tr>
        <td data-bind="name"></td>
        <td data-bind="status"
            data-bind-class="status === 'active'
              ? 'badge success'
              : 'badge inactive'"></td>
      </tr>
    </template>
  </tbody>
</div>
wildflower.component('user-table', {
  pools: { users: {} },

  init() {
    // Populate: plain objects, no proxies
    data.forEach(u => this.pools.users.add(u));
  },

  // Optional: add tick() and the same pool
  // renders every frame. Same template, same
  // data, different rendering frequency.
  // That's the only difference between a
  // display table and a particle system.
})

Built for AI-Assisted Development

Because WildflowerJS is standard HTML and JavaScript, AI code assistants already know how to write it. There's no custom syntax to hallucinate or compiler quirks to work around. The code an AI generates runs exactly as written, with no build step between generation and execution.

We go further. WildflowerJS ships an AI-optimized reference page with patterns, anti-patterns, and examples designed for code generation context windows. Our llms.txt file follows the llms.txt convention for machine-readable documentation.

And for structured app generation, our Universal App Manifest lets you describe an entire application as a JSON schema (components, state, computed properties, methods, templates) and have an AI generate the working code from the manifest, mediated through framework-specific idiom files.

You: "Build me a todo app with
WildflowerJS"

AI reads llms.txt or ai-assistant.html
     ↓
Generates standard HTML + JS
     ↓
<div data-component="todo-app">
  <input data-model="newItem">
  <button data-action="addItem">
    Add
  </button>
  <ul data-list="items">
    <template>
      <li data-bind="text"></li>
    </template>
  </ul>
</div>
     ↓
Open in your browser. It works, and you can read and understand the code.

Modals & Dialogs

The canonical pattern for share dialogs, confirmations, and any UI that overlays the page. Five framework features combine here, and each has a non-obvious "right" choice.

Key Concept: A modal is a composed pattern, not a primitive. Get the five small decisions right (click-outside, Esc-to-close, input binding, post-render focus, multi-class toggles) and avoid reaching for unneeded workarounds. The Project Management demo hosts every one of its forms through this pattern; the code below is the same shape, condensed.

The Complete Pattern

A working share dialog with click-outside, Esc-to-close, copy-to-clipboard, and auto-select on open. Read the code, then the decision table below explains every line that could have been written a different way.

<div data-component="share-document">
    <button class="btn btn-primary" data-action="openDialog">
        Share this document
    </button>
    <span class="ms-2 text-muted" data-show="lastAction" data-bind="lastAction"></span>

    <!-- data-event-self: only fires when the click target IS the scrim,
         not a click that bubbled up from the dialog box.
         position:fixed on .scrim escapes most stacking contexts;
         see "When you need a portal" below for the exceptions.
         data-cloak: hide the element until the framework has initialized
         and processed data-show, preventing a brief flash of the modal
         open on first paint. The framework removes the attribute on init. -->
    <div class="scrim" data-show="open"
         data-action="closeDialog" data-event-self data-cloak>
        <div class="dialog">
            <h3>Share link</h3>
            <p class="muted">Anyone with this URL can view the document.</p>

            <div class="urlbox">
                <!-- data-bind on <input> writes the .value PROPERTY,
                     bypassing the input dirty-value flag.
                     Do NOT use data-bind-attr={value: url}. -->
                <input type="text" data-bind="shareUrl" readonly>
                <button data-action="copyUrl"
                        data-bind-class="{ok: copied}"
                        data-bind="copyLabel">Copy</button>
            </div>

            <footer>
                <button class="btn btn-ghost" data-action="closeDialog">Done</button>
            </footer>
        </div>
    </div>
</div>
wildflower.component('share-document', {
    state: {
        open: false,
        shareUrl: '',
        copied: false,
        lastAction: '',
    },

    computed: {
        copyLabel() { return this.state.copied ? 'Copied' : 'Copy'; },
    },

    openDialog() {
        this.state.shareUrl = 'https://example.com/s/' + Math.random().toString(36).slice(2, 10);
        this.state.open = true;
        this.state.lastAction = '';        // clear "Dialog closed" from a prior cycle
        // Instance prop (not state): one-shot flag, no extra reactive pass.
        this._focusOnNextUpdate = true;
    },

    closeDialog() {
        this.state.open = false;
        this.state.copied = false;
        this.state.lastAction = 'Dialog was closed';
    },

    copyUrl() {
        try {
            navigator.clipboard.writeText(this.state.shareUrl);
        } catch (e) { /* older browsers: skip silently */ }
        this.state.copied = true;
        clearTimeout(this._copyTimer);
        this._copyTimer = setTimeout(() => { this.state.copied = false; }, 1500);
    },

    // onUpdate fires via requestAnimationFrame AFTER the DOM is committed.
    // This is WildflowerJS's $nextTick equivalent. Use it for focus,
    // .select(), scroll-into-view, third-party widget init.
    onUpdate() {
        if (this._focusOnNextUpdate) {
            this._focusOnNextUpdate = false;
            this.$el('input').el?.select();
        }
    },

    // Esc-to-close: a global shortcut while the modal is open, not a
    // widget-scoped key. Use a document listener. See "Esc-to-close: when
    // to use what" below for the data-event-key-* distinction.
    init() {
        this._onKey = (e) => {
            if (e.key === 'Escape' && this.state.open) this.closeDialog();
        };
        document.addEventListener('keydown', this._onKey);
    },

    destroy() {
        document.removeEventListener('keydown', this._onKey);
        clearTimeout(this._copyTimer);
    },
});
/* Uses the docs site's theme variables so the dialog adapts to
   light/dark mode. Outside this site, swap these for your own
   tokens (e.g. --modal-bg, --text-color, --border-color).         */

.scrim {
    position: fixed; inset: 0;
    background: rgba(0, 0, 0, .45);
    display: flex; align-items: center; justify-content: center;
    z-index: 100;
}
.dialog {
    width: 420px; max-width: calc(100vw - 32px);
    background: var(--modal-bg);
    color: var(--text-color);
    border: 1px solid var(--border-color);
    border-radius: 6px;
    box-shadow: 0 20px 60px rgba(0, 0, 0, .35);
    padding: 18px 20px;
}
.dialog h3 { margin: 0 0 4px; color: var(--text-color); }
.dialog .muted { color: var(--text-secondary); font-size: 13px; }
.urlbox {
    display: grid; grid-template-columns: 1fr auto; gap: 6px;
    margin: 12px 0;
}
.urlbox input {
    font-family: ui-monospace, monospace; font-size: 12px;
    padding: 8px 10px;
    background: var(--code-bg);
    color: var(--text-color);
    border: 1px solid var(--border-color);
    border-radius: 3px; min-width: 0;
}
.urlbox button {
    padding: 0 14px;
    background: var(--accent-color); color: #fff;
    border: none; border-radius: 3px; font-weight: 600; cursor: pointer;
}
.urlbox button.ok { background: #2f8f4f; }
.dialog footer { display: flex; justify-content: flex-end; margin-top: 8px; }
.btn-ghost {
    background: transparent;
    color: var(--text-color);
    border: 1px solid var(--border-color);
    padding: 6px 14px; border-radius: 3px; cursor: pointer;
}
.btn-ghost:hover { background: var(--code-bg); }
Live Preview

Decision Table

Each row is a place where two patterns can both work. The "Use" column is the idiomatic WildflowerJS primitive built for the job; the "Don't" column is the equivalent done by hand, more lines for the same result.

Concern Use Don't use Why
Click on scrim closes, click on dialog doesn't data-event-self on the scrim if (event.target === element) inside the handler, or stopPropagation() on the dialog Built-in modifier. Reads as: "fire this action only when the click originates ON this element, not on a descendant." One attribute beats four lines of handler logic, and the framework filters before your handler runs.
Display a value in a readonly text input data-bind="url" on <input> data-bind-attr="{value: url}" or imperative input.value = ... data-bind on form inputs writes the .value property. The attribute path (setAttribute) sets the value content attribute, which only seeds the initial render; the displayed .value property diverges from it on every subsequent update.
Focus / select / scroll after a conditional element appears Instance-prop flag + onUpdate setTimeout(..., 50) after toggling state onUpdate fires via requestAnimationFrame after the DOM commits. No magic delay, no timing race when slow devices are slower than 50ms.
One-shot flag for post-render imperative work Instance prop (this._flag = true) State field (this.state.flag = true) State-based costs two reactive passes for nothing: one to set, one to clear. Instance props are the documented escape hatch for "do this once, never bind." See "One-shot Flags" below.
Esc-to-close while a modal is open document.addEventListener('keydown', ...) in init / removed in destroy data-event-key-escape on a component element Esc-to-close-this-modal is conceptually a global shortcut. Declarative key modifiers require focus to be scoped to the listening element, which fights the focus-the-URL-input pattern. See "Esc-to-close: when to use what" below.
Toggle multiple CSS classes from booleans data-bind-class="{ok: copied, error: hasErr}" Ternary chain or string concatenation in a computed Object form reads as a truth table. Keys are bare JS identifiers; they don't need quoting inside the double-quoted HTML attribute.
Escape an ancestor that breaks fixed positioning data-portal="body" on the scrim Bumping z-index to escape a containing block Use a portal when an ancestor creates a containing block (transform, filter, perspective, will-change, contain) that traps position: fixed. Use z-index for stacking order within the same containing block (e.g., a confirm dialog on top of a share dialog, both un-portaled). The two solve different problems; don't reach for z-index when the issue is a trapped containing block, and don't reach for a portal when the issue is layering order. See "When you need a portal" below.

One-shot Flags: Instance Prop vs. State

The _focusOnNextUpdate flag is stored on this directly, not on this.state. Both work, but the instance-prop form is the right escape hatch for "do this once, post-render":

// GOOD: instance prop. Set once, read once, no reactive pass.
openDialog() {
    this.state.open = true;
    this._focusOnNextUpdate = true;
}

onUpdate() {
    if (this._focusOnNextUpdate) {
        this._focusOnNextUpdate = false;
        this.$el('input').el?.select();
    }
}

// WORKS BUT WASTEFUL: state-based. Setting and clearing each trigger a
// reactive flush. For a one-shot focus, two extra passes for no gain.
state: { open: false, focusFlag: false },
openDialog() {
    this.state.open = true;
    this.state.focusFlag = true;     // reactive pass #1
}
onUpdate() {
    if (this.state.focusFlag) {
        this.state.focusFlag = false; // reactive pass #2
        this.$el('input').el?.select();
    }
}

Use the instance-prop pattern any time the flag is read by lifecycle hooks or imperative code and never bound to the DOM. The same escape hatch is documented for third-party handles (AudioContext, IntersectionObserver, scroll observers) on the Lifecycle Hooks page.

Esc-to-close: When to Use What

WildflowerJS has two ways to handle keyboard input. They serve different jobs:

Document listener: global-while-X-is-true

When the key should fire regardless of where focus happens to be:

  • Esc closes the currently-open modal
  • Cmd/Ctrl+K opens a global command palette
  • ? shows a keyboard-shortcut overlay
init() {
    this._onKey = (e) => {
        if (e.key === 'Escape' && this.state.open) this.closeDialog();
    };
    document.addEventListener('keydown', this._onKey);
},
destroy() {
    document.removeEventListener('keydown', this._onKey);
},

data-event-key-*: widget-scoped shortcuts

When the key should only fire while a specific element is focused:

  • Enter submits a search input
  • Arrow keys navigate a focused listbox
  • Esc clears a focused autocomplete
<input data-action="keyup:search" data-event-key-enter>
<ul role="listbox" data-action="keydown:moveDown" data-event-key-down tabindex="0">...</ul>

Supported keys: enter, tab, delete, esc, escape, space, up, down, left, right, backspace. Modifier-only attributes: data-event-key-ctrl, data-event-key-alt, data-event-key-shift, data-event-key-meta. Any other key name works via data-event-key-<name>.

The decision criterion: ask "where should focus be when this fires?" If the answer is "wherever the user happens to be," it's a document listener. If the answer is "in this specific widget," it's data-event-key-*. The most common modal mistake is using data-event-key-escape for modal close, then fighting focus management.

Confirmation Dialogs and Multiple Modes

For a single component that hosts several dialog flavors (share, confirm-revoke, settings), derive the dialog content from a single source-of-truth state field and switch modes with one flag.

The Complete Pattern above used a plain open boolean because there was only one dialog flavor. Once a component owns two or more flavors, replace the boolean with a dialogMode string ("share", "confirm", or null) and derive scrimOpen from it as a computed. Both conventions are correct; the choice is just "how many flavors does this component need to show":

wildflower.component('saved-documents', {
    state: {
        activeId: null,
        dialogMode: null,   // 'share' | 'confirm' | null
        pendingIds: [],
    },

    computed: {
        scrimOpen()      { return this.state.dialogMode !== null; },
        isShareMode()    { return this.state.dialogMode === 'share'; },
        isConfirmMode()  { return this.state.dialogMode === 'confirm'; },

        // Dialog content derived from activeId, no mirror state on open.
        activeDoc() {
            return this.state.activeId
                ? this.state.documents.find(d => d.id === this.state.activeId)
                : null;
        },
        dialogTitle() { return this.computed.activeDoc?.name || ''; },
    },

    openShare(event, element, details) {
        this.state.activeId = details.item.id;
        this.state.dialogMode = 'share';
    },
    askConfirm(event, element, details) {
        this.state.pendingIds = [details.item.id];
        this.state.dialogMode = 'confirm';
    },
    closeDialog() {
        this.state.dialogMode = null;
        this.state.activeId = null;
    },
});
<div class="scrim" data-show="scrimOpen"
     data-action="closeDialog" data-event-self data-cloak>
    <div class="dialog" data-show="isShareMode">
        <h3 data-bind="dialogTitle"></h3>
        ...
    </div>
    <div class="dialog confirm" data-show="isConfirmMode">
        <h3>Are you sure?</h3>
        ...
    </div>
</div>

The scrim's data-event-self and Esc listener cover both modes without duplication. Each dialog body uses data-show against a mode flag, so only one is visible at a time. Dialog content like dialogTitle is a computed off activeId, so opening, switching, or reopening the dialog never requires copying fields into mirror state. The Esc handler from the Complete Pattern carries over unchanged except that the gate becomes this.computed.scrimOpen (or equivalently this.state.dialogMode !== null) instead of this.state.open.

Transitioning Between Modes

When the next mode uses the same scrim (share to confirm, settings to about), just flip dialogMode directly. The scrim stays open, only the inner data-show flips, and the user sees one dialog replace the other instantly.

When the dialog box itself needs a visible exit animation before the next one appears, schedule the next mode flip after the animation completes. Either listen for the transitionend event on the dialog, or schedule the next flip via setTimeout matched to your animation duration:

revokeFromShare() {
    const id = this.state.activeId;
    this.state.dialogMode = null;         // close share dialog (triggers exit anim)
    setTimeout(() => {
        this.state.pendingIds = [id];
        this.state.dialogMode = 'confirm';  // open confirm after anim settles
    }, 160);                                // match your animation duration
}

Pick the timing path that fits your design: instant flip if the two dialogs feel like one continuous surface, animated handoff if they should feel distinct.

When You Need a Portal

The example above uses position: fixed; inset: 0 on the scrim and renders the modal in its natural DOM location. This works as long as no ancestor creates a containing block for fixed-positioned children. If yours does, the scrim renders relative to that ancestor instead of the viewport, and the modal can end up clipped, off-center, or behind unrelated content.

Ancestors that create a containing block for position: fixed:

  • transform with any value other than none
  • filter, backdrop-filter
  • perspective with any value other than none
  • will-change: transform or will-change: filter
  • contain: layout, contain: paint, contain: strict

When any of these apply to a parent of your modal, add data-portal="body" to the scrim:

<div class="scrim" data-show="open"
     data-action="closeDialog" data-event-self
     data-portal="body" data-cloak>
    <div class="dialog">...</div>
</div>

The framework teleports the scrim (and its dialog contents) to <body> at the moment open becomes true, and moves it back when open becomes false. All bindings, event handlers, and reactivity continue to work; the source component still owns the modal even though the DOM lives elsewhere. See Portals for the full contract.

If you're not sure whether you need a portal, ship without one first. The symptom is unmistakable: the scrim renders at the wrong size or position when opened, often clipped to the size of a parent container. Adding data-portal="body" at that point is a one-attribute fix.

Accessibility

The patterns above cover the reactive wiring. A production-ready modal also needs ARIA roles and focus management, which are responsibilities of your markup and surrounding code rather than the framework. At minimum:

<div class="scrim" data-show="open"
     data-action="closeDialog" data-event-self data-cloak
     role="dialog" aria-modal="true"
     aria-labelledby="dialog-title">
    <div class="dialog">
        <h3 id="dialog-title">Share link</h3>
        ...
    </div>
</div>
  • role="dialog" and aria-modal="true" tell assistive tech this is a modal region.
  • aria-labelledby (or aria-label) gives the modal an accessible name. Point it at the heading element so screen readers announce the dialog by its title.
  • Focus trap. Tab and Shift+Tab should cycle within the dialog while it's open, not leak out to background page elements. The framework doesn't ship a focus-trap primitive; either write a small handler that intercepts keydown on Tab and wraps focus, or pull in a small library (e.g., focus-trap) and start/stop it in openDialog/closeDialog.
  • Restore focus on close. Save document.activeElement in openDialog before any state flip and call .focus() on it in closeDialog, so keyboard users return to the trigger button they came from.
  • The Project Management demo's pm-modal-host uses this exact attribute set; read it for a working reference.
openDialog() {
    this._triggerEl = document.activeElement;   // capture before state flips
    this.state.open = true;
    this._focusOnNextUpdate = true;
},
closeDialog() {
    this.state.open = false;
    this._triggerEl?.focus();
},

Capturing document.activeElement on the same instance prop that hosts other one-shot flags keeps the pattern uniform. Capturing in init instead of openDialog would grab whatever happened to be focused at mount time, which is rarely the right target.

These are not in the canonical example to keep the wiring lessons clean, but every modal you ship should have them.

Anti-patterns

Reaching for setTimeout after a state toggle

If code looks like this, the framework has a hook that does what you want:

// BAD
this.state.open = true;
setTimeout(() => this.$el('input').el.select(), 50);

// GOOD
this.state.open = true;
this._focusOnNextUpdate = true;
// ... and check the flag in onUpdate()

Imperatively writing .value through $el

The framework writes .value for you when you use data-bind on an input. The only time you need imperative .value assignment is for inputs that aren't bound to component state at all (e.g., a third-party widget's hidden field).

// BAD
openDialog() {
    this.state.open = true;
    setTimeout(() => { this.$el('input').el.value = this.computed.shareUrl; }, 50);
}

// GOOD: data-bind="shareUrl" on the <input> in HTML;
// no imperative .value assignment needed.

data-bind-attr for input values

data-bind-attr calls setAttribute, which sets an input's value content attribute but not its displayed .value property. The two diverge as soon as the input has been rendered once, so subsequent updates won't appear. Use data-bind on inputs (writes the property); reserve data-bind-attr for true HTML attributes like href, src, aria-*, and title.

Wrapping the dialog body in a click-stop handler

An older pattern (and one the Patterns page still shows) puts data-action="stopPropagation" on the dialog box to keep clicks inside the dialog from reaching the scrim. data-event-self on the scrim is the modern equivalent and doesn't need a custom stopPropagation method:

<!-- Older: stop-propagation guard -->
<div class="scrim" data-action="cancel">
    <div class="dialog" data-action="stopPropagation">...</div>
</div>

<!-- Better: event-self filter -->
<div class="scrim" data-action="cancel" data-event-self>
    <div class="dialog">...</div>
</div>

See Also

  • Portals: for understanding why data-portal="body" matters and what stacking contexts can clip your modal.
  • Lifecycle Hooks: for onUpdate, init, and destroy contracts.
  • Advanced Events: for the full event modifier surface (data-event-stop, data-event-prevent, data-event-debounce, data-event-key-*).
  • Content Binding: for how data-bind behaves on form inputs vs. other elements.
  • Patterns: Confirmation Modal: a shorter copy-and-paste recipe focused on confirm-and-delete flows (browse to the "Confirmation Modal" entry in the patterns sidebar).
Previous Portals
Next Transitions
Related patterns: Modal Dialog