Versions Compared

Old Version 1

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

Saved on

compared with

New Version 2

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

Saved on

Key

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

(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Lookup Input

Link to Figma: tba

Overview

  • The Lookup Input Component is a specialized form control for searching and selecting items from large datasets.
  • It displays a read-only input field that opens a dialog with a searchable data grid when clicked.
  • The component is useful when traditional dropdowns are impractical due to the dataset size.
  • It improves efficiency by combining search, selection, and data persistence in one control.

...

  • dataTestId – Sets the testing hook ID for automated testing. For example, setting to "customer-lookup" allows test scripts to reliably locate this component.

Guidelines

[NO DATA AVAILABLE]

Accessibility

...

Usage

  • Use Lookup Input for large, searchable datasets. Connect to data with getElementsDataSourceId, configure the grid via elements, and keep performance with enablePagination + pageSize.
  • Store a stable identifier and show a readable label: use valueKey (stored), displayValueKey (shown), and submit using dataField with controlsRequestType.
  • Persist frequent selections across sessions with saveInLocalStorage.
  • Pre-fill only when it’s clearly correct using defaultValue.

Sizing & Layout

  • Curate columns to only what helps selection and order them by importance using elements.
  • Balance density and scanning effort by tuning pageSize.
  • Ensure the input shows a recognizable value by choosing an appropriate displayValueKey.

States & Feedback

  • Enforce mandatory selection with validation.required.

Visibility & Authorization

  • Show or hide the control with hidden when it’s irrelevant.
  • Indicate permission constraints by disabling interaction via authorizationDisable.

Content & Localization

  • Localize user-facing copy with labelTranslations, dialogTitleTranslations, and dialogSubtitleTranslations.
  • Align the displayed value to user expectations by selecting an appropriate displayValueKey and reinforcing it in elements.

Dos & Don’ts

DoDon’tArticle setting(s)
Store a stable ID and show a readable name.Store the display name as the value.valueKey, displayValueKey, dataField
Localize label, dialog title, and subtitle.Ship English-only strings.labelTranslations, dialogTitleTranslations, dialogSubtitleTranslations
Keep the grid focused on decisive fields.Show every backend column.elements
Use pagination for large datasets.Load thousands of rows at once.enablePagination, pageSize
Persist frequent selections across sessions.Force users to reselect on every visit.saveInLocalStorage
Mark essential relationships as required.Let forms submit with missing relations.validation.required
Respect permissions by disabling interaction.Hide the control when users need to see the value.authorizationDisable
Hide the field when irrelevant.Show an inert field with no purpose.hidden
Pre-configure query parameters on init.Change server filters unpredictably mid-session.ON_INIT, getEntityCollectionHttpRequestParametersMap
Submit data through the intended channel.Rely on defaults that mismatch your API.controlsRequestType, dataField
Provide a stable test hook for QA.Select the control via brittle selectors.dataTestId
Set a safe, obvious default only when appropriate.Pre-fill with a misleading value.defaultValue

Accessibility

  • Provide localized, descriptive labeling and dialog context via labelTranslations, dialogTitleTranslations, and dialogSubtitleTranslations.
  • Keep titles concise and add secondary details in subtitles using dialogTitleTranslations and dialogSubtitleTranslations.
  • Convey input meaning through a readable displayValueKey; reinforce with clear columns in elements.
  • Reflect input rules and state with validation.required and readonly to ensure assistive tech announces necessity and non-editability.
  • Supply a stable selector for automated accessibility checks using dataTestId.
  • Avoid cognitive overload by limiting columns in elements and tuning pageSize to a manageable amount.
  • Manage focus and perception appropriately: remove irrelevant controls from the flow using hidden, or keep them visible but non-interactive with authorizationDisable when users must see existing values.