Versions Compared

Old Version 3

changes.mady.by.user GE-DevDoc-Bot

Saved on

compared with

New Version 4

changes.mady.by.user GE-DevDoc-Bot

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • validation – Configures validation rules for the combobox, including:
  • required – When set to true, the field must have a selection before the form can be submitted.

Guidelines

[NO DATA AVAILABLE]

Accessibility

...

Usage

  • Use the combobox when a user must choose one value from a list that can be static or API-driven; connect via useStaticData + staticData or dataSourceId + dataSourcePath with modelValue/modelDisplayValue.
  • Provide a default only when it prevents busywork; set defaultValue, and avoid preselecting when an explicit choice is required with validation.required.
  • Let users undo optional selections with a clear affordance by enabling showClearIcon.
  • Persist the selection across sessions only when beneficial by using saveInLocalStorage.
  • Keep option content simple and scannable by ensuring the field mapped to modelDisplayValue contains concise, single-line text; avoid composing multi-line or compound labels inside the list.
  • When “no value” is a valid outcome, include an explicit “None” option in staticData (or via your API), keep validation.required: false, and enable showClearIcon to make reversal easy.

Sizing & Layout

  • Keep visible option text concise and scannable by mapping it to a human-readable field through modelDisplayValue.
  • Order options logically (alphabetical, numerical, or by expected frequency) by pre-ordering staticData or requesting a sort via getEntityCollectionHttpRequestParametersMap on the field shown by modelDisplayValue.

Data-Driven / Conditional Behavior

  • Match data volume to UX: paginate large collections with pageSize, and use loadAll only for small datasets.
  • Provide predictable filtering while typing by aligning searchKey with a user-recognizable field (often the one used by modelDisplayValue).
  • Align server-side filtering/sorting with the user’s search by setting complementary parameters in getEntityCollectionHttpRequestParametersMap for the same field as searchKey.
  • Emit the payload your consumer expects: submit just the key with emitObject: false (using modelValue) or the full object with emitObject: true.
  • For static lists, ensure each option includes fields used by modelValue and modelDisplayValue in staticData.

Content & Localization

  • Provide a clear, localized field label with labelTranslations. Use sentence-style capitalization, avoid colons, and keep labels brief (1–2 words where possible).
  • Help authors find the control during authoring by naming it clearly with displayName.

Dos & Don’ts

DoDon’tArticle setting(s)
Localize the field label for all supported locales and keep it short in sentence-style capitalization.Hardcode the label in one language or add punctuation like colons.labelTranslations
Map option value and label explicitly to the correct fields.Swap value/label and confuse submissions.modelValue, modelDisplayValue
Write option labels as short, parallel phrases and ensure the displayed text comes from a concise field.Mix long sentences, inconsistent parts of speech, or jargon across options.modelDisplayValue, staticData
Include a “None” option when no selection is valid, make the field not required, and allow easy clearing.Force a choice when “no value” is acceptable.staticData, validation.required, showClearIcon
Sort options in a logical, scannable order (e.g., alphabetical) via data order or server sort.Leave options in an arbitrary order that slows scanning.staticData, getEntityCollectionHttpRequestParametersMap
Filter on a field users recognize.Search by an internal ID that users don’t understand.searchKey, modelDisplayValue
Provide a default only when useful.Preselect when an explicit decision is required.defaultValue, validation.required
Persist only when appropriate for the same user/session.Persist sensitive or context-specific choices.saveInLocalStorage
Emit the payload shape your consumer expects.Break integrations by switching payload shapes silently.emitObject, dataField
Initialize deterministically before interaction and clean up on removal.Defer setup until first click or leave dangling listeners.ON_INIT, ON_INIT_BASED_ON_USER_VIEW, ON_DESTROY

Accessibility

  • Provide a localized, explicit label so assistive tech announces the control meaningfully (labelTranslations).
  • Prefer human-readable labels for both display and filtering (modelDisplayValue, searchKey); keep them short and parallel.
  • Prevent non-functional interaction in read-only contexts with readonly.
  • Keep submission semantics unambiguous by mapping value/label correctly (modelValue, modelDisplayValue).
  • Avoid forcing a choice unnecessarily by pairing validation.required appropriately with defaultValue and showClearIcon.
  • Provide an easy way to undo choices for optional fields (showClearIcon).
  • Keep list order predictable by sorting labels (server-side or in data) so screen-reader users can anticipate positions (staticData, getEntityCollectionHttpRequestParametersMap).