Overview

About AutoComplete (React)

AutoComplete (React) is a pluggable web widget that gives Mendix apps a fast,

searchable dropdown for selecting association values. It is a ground-up React

Client rewrite of the classic AutoComplete for Mendix widget, rebuilt without

any Dojo or jQuery dependency so it renders natively in the modern Mendix

React Client.

What it does

The widget lets a user type a few characters and pick a related object to set

on a reference or reference-set association. It works where the

standard Reference Selector and the new Combo Box fall short — large datasets,

server-side search, custom result formatting, and per-item control.

Search modes

• XPath — filters the data source directly in the database using
• starts-with or contains matching on a chosen string attribute, with an
• optional sort order and constraints.
• Microflow — calls a microflow on every keystroke (after a debounce and a
• minimum input length) so search logic and constraints live in your model.
• Searches fire independently and do not block one another; the result of the
• most recent keystroke is always the one displayed.
• Microflow (Cached) — runs a microflow once on load (and on context
• refresh, optionally gated by a boolean attribute), then filters the cached
• results client-side for instant, low-latency typing.

Key features

• Reference and reference-set (single and multi-select) associations from one
• widget.
• variable-to-attribute mappings, so each row can show rich, multi-attribute
• content.
• Configurable minimum input length, search delay (debounce) and sort order.
• Allow-clear, open-on-focus, select-on-close, disable-via-attribute, and
• per-item disabling with a tooltip.
• A "no results" state that can be plain text or a button wired to a microflow
• (ideal for "create new" flows).
• Dropdown portaling via a CSS parent selector, so the list renders correctly
• inside modals and constrained layouts.
• Fully configurable strings: placeholder, "input too short" (with
• ${minLength} / ${remainLength} tokens) and "searching" text.
• An on-change action to react to selection changes.

Typical use cases

• Selecting a customer, product, account or any lookup value from thousands of
• records where a plain drop-down would be unusable.
• Type-ahead search backed by business logic in a microflow.
• Rich result rows showing a code plus a description, or a name plus a status.
• "Search and create" patterns where an empty result offers a button to add a
• new record.

Requirements and notes

• Mendix React Client (Web). The widget is not offline-capable in XPath or
• per-keystroke microflow modes; use Cached mode for the closest offline-like
• behaviour.
• Search attributes are String type, consistent with the original widget.

Documentation

AutoComplete (React) — Documentation

Typical usage scenario

AutoComplete (React) is used wherever a user needs to pick a related object

from a list that is too large or too dynamic for a standard drop-down. Instead

of loading every option up front, the user types a few characters and the

widget searches — in the database, through a microflow, or over a cached set —

and shows only the matching results.

Common scenarios include:

• Selecting from large lookup tables — choosing a customer, product,
• account, city or any reference value out of hundreds or thousands of records,
• where the built-in Reference Selector or Combo Box would be slow or
• unusable.
• Server-side / business-logic search — when the list of selectable
• objects must be produced or constrained by a microflow (security rules,
• cross-entity joins, external data) rather than a simple XPath.
• Rich result rows — showing more than a single label per option, e.g. a
• code plus a description, or a name plus a status badge, using HTML result
• templates.
• Multi-select associations — populating a reference-set (many-to-many)
• from the same searchable control.
• "Search and create" flows — when a search returns nothing, offering a
• button that runs a microflow to create the missing record.

It solves the core problem that the classic Dojo/jQuery "AutoComplete for

Mendix" widget does not render at all in the Mendix React Client. This is a

native React rewrite that restores that advanced autocomplete capability for

modern Mendix apps.

Features and limitations

Features

• Reference and reference-set support — single-select and multi-select
• associations from one widget.
• Three search modes:
  • XPath — filters the data source in the database with starts-with or
  • contains matching on a chosen String attribute, with optional sort order.
  • Microflow — calls a microflow per keystroke (after debounce and minimum
  • input length) so all search logic lives in your model. Searches fire
  • independently and do not block one another; the result of the most recent
  • keystroke is always the one displayed.
  • Microflow (Cached) — runs a microflow once on load (and on context
  • refresh, optionally gated by a boolean attribute), then filters the cached
  • results client-side for instant typing.
• Templating — plain-text "selected" template and HTML "result" template,
• driven by variable-to-attribute mappings, so each row can show rich content.
• Configurable behaviour — minimum input length, search delay (debounce),
• and sort order.
• Control options — allow-clear, open-on-focus, select-on-close,
• disable-via-attribute (plus automatic disable when the association is
• read-only), and per-item disabling with a tooltip.
• No-results handling — display text or a button wired to a microflow.
• Modal-friendly — dropdown portaling via a CSS parent selector so the
• list renders correctly inside modals and constrained layouts.
• Configurable strings — placeholder, "input too short" (supports
• ${minLength} and ${remainLength} tokens) and "searching" text.
• On-change action — run a microflow/nanoflow when the selection changes.
• Studio Pro editor preview — the widget renders sensibly in design mode.

Limitations

• Web only. The widget targets the Mendix React Client on the Web
• platform. It is not built for native mobile.
• Not offline-capable in XPath or per-keystroke Microflow modes, because
• both require a live server round-trip per search. Use Microflow (Cached)
• mode for the closest offline-like behaviour.
• Search attribute must be String. Consistent with the original widget,
• the searchable attribute (XPath and Cached filtering) is limited to String
• type.
• Search microflow contract. In Microflow mode the widget writes the term
• to the configured search-string attribute and reloads the data source; your
• microflow / data source must read that attribute to filter results.
• Client-side filtering scale (Cached mode). All cached objects are held in
• the browser and filtered in memory, so very large cached sets increase
• client memory use. Prefer XPath or Microflow mode for very large datasets.

Dependencies

• Mendix Studio Pro with the React Client enabled (this widget is a
• React pluggable widget and will not run on the legacy Dojo client).
• A context object with the reference / reference-set association you want
• to set (the widget requires entity context).
• A data source (entity path or XPath) over the associated entity to
• supply the selectable objects.
• For Microflow / Microflow (Cached) modes: a search microflow and, for
• Microflow mode, a String attribute on the context to hold the search
• term.

There are no external npm, CDN or third-party service dependencies — no Dojo,

no jQuery, no Select2. Everything ships inside the .mpk.

Installation

1. Download the widget from the Mendix Marketplace (or import the
2. com.lowcodelabs.widgets.AutoCompleteReact.mpk file).
3. widget appears in the Toolbox.
4. Ensure your app is configured to use the React Client (Project
5. Settings > check the client/runtime version supports the React Client).
6. Open a page, place the widget inside a data view (or other context that
7. provides the entity holding the association), and configure its properties
8. (see Configuration).
9. Run locally to verify it appears and searches as expected.

Configuration

Place the widget in a context that provides the owner of the association, then

configure the property groups:

Search (required)

• Select source — the reference or reference-set association to set.
• Selectable objects — the data source (entity path / XPath) that lists
• the objects the user can pick.
• Minimum input length — characters required before searching (default 3).
• Search type — XPath, Microflow, or Microflow (Cached).
• Search delay — debounce in milliseconds before a search fires
• (default 300; set 0 to search on every keystroke).

Search — XPath / Cached filtering

• Search method — starts-with or contains.
• Search attribute — the String attribute to match on.

Search — Microflow

• Search string attribute — context attribute that receives the typed term
• before the search microflow runs.
• Search microflow — runs on each keystroke to refresh the selectable
• objects.

Search — Microflow (Cached)

• Refresh cache via attribute — optional boolean; when true the cache is
• refreshed on context change.

Result display

• Selected template — plain-text template for the chosen value
• (e.g. ${Label}).
• Result template — HTML template for each dropdown row (wrapped in
• div.autoCompleteResult); leave empty to reuse the selected template.
• Template attributes — map each ${VariableName} token to an attribute
• on the selectable object.
• Sort order — one or more attributes with ascending/descending direction
• (applied to the XPath data source).

Control display

• Allow clear, Disabled via attribute, Select on close,
• Parent selector (CSS selector for dropdown portaling, e.g. inside a
• modal), Disable dropdown option (per-item boolean) with Disable list
• tooltip, and Open on focus.

No results

• Display type (Text or Button), No results text, and — for the button
• — a Search string attribute and No results microflow.

Strings

• Placeholder text, Input too short text (supports ${minLength} /
• ${remainLength}), and Searching text.

Events

• On change — action to run when the selection changes.

Known bugs

• No known functional bugs at the time of the 1.0.0 release.
• Behavioural note (not a bug): in Microflow mode the "Searching…" indicator is
• cleared either when the search settles or after an internal safety timeout
• (15 seconds). A microflow that never returns will therefore stop showing
• "Searching…" after that timeout rather than hanging indefinitely.

Please report issues via the Marketplace listing or the project repository so

they can be triaged and fixed.

Frequently Asked Questions

Does this work in the old (Dojo) Mendix client?

No. This is a React pluggable widget for the Mendix React Client. Use it in

apps configured for the React Client. (The original Dojo AutoComplete widget

does not render in the React Client, which is why this rewrite exists.)

Can I use it for many-to-many (reference-set) associations?

Yes. It supports both reference (single-select) and reference-set

(multi-select) associations from the same widget.

Why do I need a microflow for the microflow search modes?

In Microflow mode the widget writes the search term to a String attribute and

reloads the data source, so your microflow (or the data source it backs) reads

that attribute to filter and return matching objects. This keeps the search

logic and any security constraints in your model.

Can I search on a number or date attribute?

The searchable attribute is limited to String type, consistent with the

original widget. To search a non-string value, expose or derive a String

attribute to match on.

The dropdown is clipped inside a modal / popup. How do I fix it?

Set the Parent selector property to a CSS selector for the container the

dropdown should portal into (for example the modal dialog element). Leave it

empty to render inline.

Does it work offline?

Not in XPath or per-keystroke Microflow modes, which both need a live server

round-trip. Microflow (Cached) mode loads once and filters in the browser, so

it is the closest to an offline-capable option.

How do I offer a "create new" option when nothing matches?

Set the No results Display type to Button, provide a No results

microflow, and (optionally) a Search string attribute so your microflow

receives what the user typed.