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

Combobox

[!WARNING] This article contains information on the Combobox and Multi Combobox. It therefor might be misleading.

Overview

• The Dynamic Combobox Component is a form control with a dropdown selection interface.
• It allows users to select a single value from a list of options.
• It supports both static data and dynamic data from server endpoints.
• Features include search, pagination, and customizable display formats.

Specs

Tokens

Structure

• The Combobox connects to either static data or external data sources through the Data Management configuration.
• The structure ensures that the selected value is stored and submitted consistently with other form fields.

(Configured in Genereal Properties)

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

(Configured in Non-Visual Properties)

• saveInLocalStorage – Determines whether the combobox's selected value is preserved in local storage. When enabled, the user's selection persists between page reloads or browser sessions, improving user experience.

Data Management

(Configured in Non-Visual Properties)

• useStaticData – Determines whether the component uses static data defined in the component configuration or fetches data from an API endpoint. When set to true, the component will use the data provided in the staticData property rather than calling an API.
• staticData – Defines the list of options that will be available in the dropdown when useStaticData is enabled. For example, [{"value": "corporate", "text": "Corporate Customer"}, {"value": "individual", "text": "Individual Customer"}] provides two selectable customer types.

Datasource

(Configured in Datasource)

• dataSourcePath – Specifies the path within the response data where the list of options is located. For example, if the API returns data in a nested structure, setting this to "data.customers.types" will extract the options from that location.
• getEntityCollectionHttpRequestParametersMap – Configures HTTP parameters for data fetching. This object maps additional parameters needed for the API request, such as filters or sorting options.
• dataSourceId – Specifies the data source ID for retrieving dropdown options. For example, "api/customerTypes" connects the combobox to the customer types API endpoint. This property is used when useStaticData is false.

Data Field

(Configured in Non-Visual Properties)

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

(Configured in Datasource)

• modelDisplayValue – Defines the field in the returned data objects that should be displayed in the dropdown. For example, setting to "name" will display the name property of each data object to the user.

Filtering Data

(Configured in Datasource)

• modelValue – Defines the field in the returned data objects that should be used as the value when an option is selected. For example, setting to "id" will use the id property of each data object as the value.
• searchKey – Specifies which field in the data objects should be used for filtering when users type in the combobox. For example, setting to "name" will search through the name property of data objects.
• emitObject – Controls whether the entire selected object is emitted as the value, rather than just the key field. When enabled, the complete data object is available in form submissions rather than just the ID value.

Loading Strategy

(Configured in Datasource)

• pageSize – Sets the number of items loaded per page when fetching data from the server. For example, setting to "20" will load 20 records at a time, with pagination controls allowing access to additional pages.
• loadAll – Determines whether all available data should be loaded at once rather than using pagination. When enabled, the component will attempt to fetch all records in a single request, which can be useful for smaller datasets.

Styling

(Configured in Visual Properties)

• label - Sets the field label.
• labelTranslations – Sets the field label with support for multiple languages. For example, {"en-US": "Customer Type", "de-DE": "Kundentyp"} ensures proper localization of the field label.
• showClearIcon – Controls whether an icon is displayed to clear the selected value. When enabled, a small "x" button appears in the combobox when a value is selected, allowing users to quickly reset their selection.
• defaultValue – Sets the initial value of the combobox when first rendered. For example, setting to "corporate" would pre-select the corporate customer option.
• pageSize – Sets the number of items loaded per page when fetching data from the server. For example, setting to "20" will load 20 records at a time, with pagination controls allowing access to additional pages.
• loadAll – Determines whether all available data should be loaded at once rather than using pagination. When enabled, the component will attempt to fetch all records in a single request, which can be useful for smaller datasets.

Actions & Variants

(Configured in Events)

• events – Configures the events that the component can trigger and respond to:
• ON_INIT – Triggered when the combobox component is initialized.
• ON_DESTROY – Triggered when the component is removed from the DOM.
• ON_VALUE_CHANGE – Triggered when the user selects a different option.
• ON_INIT_BASED_ON_USER_VIEW – Triggered when the component initializes in user view mode.

(Configured in Visual Properties)

• readonly – Controls whether the combobox allows user interaction. When set to true, the combobox will display its value but not allow changes, useful for display-only scenarios.

Tests

(Configured in Testing Hooks)

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

Validation

(Configured in Validation)

• 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.

Links

• Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11523-164008&t=ftfrOGkPzlG2GaTo-1
• Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/id3/3-dropdown/multi-combobox

Guidelines

Usage

• Use the combobox when a user must choose one value from a list that can be static or API-driven.
• 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).
• 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

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).