SAPUI5 Value Help Dialogs: Implementation Guide

Why Value Help Matters

Users hate typing long codes from memory. A value help dialog lets them search, filter, and pick a valid value instead of guessing. SAPUI5 ships one ready-made control for this: sap.ui.comp.valuehelpdialog.ValueHelpDialog.

Rule of thumb: if the user must pick from a list of more than ~7 options, give them a value help dialog instead of a dropdown.

---

The Basic Setup

You create the dialog in your controller, set its properties, bind it to a model, and open it from an input field's value-help button. Here is the minimum viable pattern.

onValueHelpRequest: function () {
  var oDialog = new ValueHelpDialog({
    title: "Select Material",
    supportMultiselect: false,
    key: "Matnr",
    descriptionKey: "Maktx"
  });
  oDialog.setModel(this.getView().getModel());
  oDialog.bindAggregation("table",
    "/Materials",
    new ColumnListItem({
      cells: [
        new Text({ text: "{Matnr}" }),
        new Text({ text: "{Maktx}" })
      ]
    })
  );
  oDialog.open();
}

Notice the key and descriptionKey properties. These tell the dialog which field is the value and which is its description, so the OK handler knows what to return.

---

Handling the Selection

Attach to the ok event to read the chosen token and push it back into your input field. The dialog gives you an array of Token objects.

oDialog.attachOk(function (oEvent) {
  var aTokens = oEvent.getParameter("tokens");
  if (aTokens.length) {
    oInput.setValue(aTokens[0].getKey());
    oInput.setDescription(aTokens[0].getText());
  }
  oDialog.close();
});

For multi-select, loop over the tokens and join the keys with a separator. Always handle the cancel event too, closing the dialog without touching the input.

---

Adding Filters and Search

Out of the box the dialog has a search field, but you usually want the filter bar pre-configured with meaningful fields. Add filter items so users can narrow by plant, material type, or whatever fits your data.

oDialog.setFilterItems([
  new FilterItem({ key: "Werks", label: "Plant" }),
  new FilterItem({ key: "Matnr", label: "Material" })
]);

Bind filters to the same model as the dialog. When the user hits search, the dialog applies the filters automatically — you don't need to write the filtering logic yourself.

---

Memory and Cleanup

Value help dialogs are heavy controls. Create the dialog once, keep a reference, and reuse it. Don't forget to destroy it when the view is torn down.

onExit: function () {
  if (this._oValueHelpDialog) {
    this._oValueHelpDialog.destroy();
    this._oValueHelpDialog = null;
  }
}

Leaked dialogs are one of the most common causes of sluggish Fiori apps that have been open for hours. A two-line onExit prevents it.

---

Wrapping Up

That is the full cycle: create, bind, filter, handle selection, clean up. Say you have a plant input on a purchase requisition app — this pattern gives you a searchable, filterable, multiselect-capable value help in under 60 lines of code.

Tried this in your app? Drop a comment with your use case or the trick that saved you the most time.