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

Lookup Input

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.

Specs

Tokens

Structure

• The Lookup Input consists of a read-only input field and a dialog with a searchable data grid for item selection.

(Configured in General Properties)

• displayName – Sets the display name of the component shown in the structure panel. For example, "Customer Selector" allows for easy identification of the component's purpose in the component structure.

(Configured in Visual Properties)

• saveInLocalStorage – Determines whether the field's value is preserved in the user's local storage between sessions. When enabled, the selected value will persist if the user reloads the page, providing a better user experience for complex forms.
• defaultValue – Sets the initial value to be used when the form is reset. For example, setting to "00001" would pre-select the customer with ID "00001" when the form is initially loaded or reset.

(Configured in Column)

• elements – Defines the columns configuration for the data grid displayed in the lookup dialog. This array contains DynamicTableColumnComponent objects that specify which fields to display in the dialog grid and how they should be formatted. For example, you can configure columns for customer ID, name, and status to help users identify the correct record.

(Configured in Datasource)

• getElementsDataSourceId – Specifies the data source ID for retrieving data to populate the lookup dialog. For example, "api/customers" connects the component to the customers API endpoint.
• getEntityCollectionHttpRequestParametersMap – Configures HTTP parameters for data fetching. This object maps additional parameters needed for the API request, which can include query parameters, path parameters, or fixed values that should be sent with every request.
• enablePagination – Activates server-side pagination for large datasets in the lookup dialog. When enabled, data is loaded in pages rather than all at once, significantly improving performance for tables with many records.
• pageSize – Sets the number of records displayed per page in the lookup dialog. For example, setting to 25 will display 25 records per page when pagination is enabled, providing a balance between visibility and performance.

Submit

(Configured in Datasource)

• valueKey – Defines the field in the data objects that should be used as the value when an item is selected. For example, setting to "id" will store the ID of the selected customer as the field value.
• displayValueKey – Defines the field in the data objects that should be displayed in the input field after selection. For example, setting to "name" will show the customer's name in the input field, even though the ID might be stored as the actual value.

(Configured in Non-Visual Properties)

• dataField – Defines the field name that will be used when submitting form data. For example, setting to "customerId" ensures the selected customer ID is submitted with this field name in the data object.
• controlsRequestType – Specifies how the field data is sent in HTTP requests: 'BODY', 'HEADER', or 'PATH'. For example, setting to "BODY" includes the field in the request body, which is standard for most form submissions.

Styling

(Configured in Visual Properties)

• labelTranslations – Sets the field label with support for multiple languages. For example, {"en-US": "Customer", "de-DE": "Kunde"} ensures proper localization of the field label.
• dialogTitleTranslations – Sets the title text displayed at the top of the lookup dialog with support for multiple languages. For example, {"en-US": "Select Customer", "de-DE": "Kunde auswählen"} ensures users understand the purpose of the dialog.
• dialogSubtitleTranslations – Sets an optional subtitle text displayed below the dialog title with support for multiple languages. For example, {"en-US": "Active customers only", "de-DE": "Nur aktive Kunden"} provides additional context about the displayed data.

Actions & Variants

(Configured in Visual Properties)

• hidden – Controls whether the component is visible in the form. When set to true, the component remains in the form structure but is not displayed, which is useful for conditional rendering based on other field values.
• readonly – Controls whether the lookup value can be changed by the user. When set to true, the lookup field displays its value but cannot be modified, which is useful for display-only scenarios.

(Configured in Events)

• events – Configures the events that the component can trigger and respond to:
• ON_INIT – Triggered when the component is initialized. Can be used to perform setup operations like loading initial configuration.
• ON_DESTROY – Triggered when the component is removed from the DOM. Useful for cleanup operations and releasing resources.

Validation

(Configured in Validation)

• validation – Configures validation rules for the lookup input, including:
• required – When set to true, the field must have a selection before the form can be submitted. This ensures users make a selection when the information is essential.

Authorization

(Configured in Authorization)

• authorizationDisable – Specifies a policy set that determines when the component should be disabled. For example, setting to "readOnlyPolicy" will disable the field for users who don't have edit permissions according to the specified policy.

Tests

(Configured in Testing Hooks)

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

Guidelines

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

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.