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

Single Select

Link to Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11528-200611&t=ftfrOGkPzlG2GaTo-1

Overview

• The Single Select component is a dropdown form control.
• It allows users to select a single option from a list.
• Options can come from a static list or a dynamic API endpoint.
• It is useful for forms where one choice must be made, such as categories, statuses, or roles.

Specs

Tokens

Structure

(Configured in Visual Properties)

• saveInLocalStorage - Determines whether the component's selected value is preserved in local storage between sessions.

Load Data

(Configured in Visual Properties)

• initValue - Defines an initial value that will be selected when the component is first rendered.
• defaultValue - Sets the value that will be used when the form is reset.

(Configured in Non-Visual Properties)

• useStaticData - Determines whether the dropdown options come from a static list or a dynamic data source.
• staticData - Specifies the predefined list of options when useStaticData is true.
• dataSourcePath - Specifies the path in the response data where the list of options can be found.

(Configured in Datasource Properties)

• dataSourceId - Specifies the API endpoint ID for retrieving dropdown options when useStaticData is false.
• getEntityCollectionHttpRequestParametersMap - Configures HTTP parameters for data fetching requests.
• loadAll - Determines whether all options should be loaded at once regardless of pagination settings.
• pageSize - Sets the number of options to load per page when pagination is enabled.

Submit Data

(Configured in Non-Visual Properties)

• dataField - Defines the field name that will be used when submitting form data.
• controlsRequestType - Specifies how the field data is sent in HTTP requests: 'BODY', 'HEADER', or 'PATH'.
• emitObject - Determines whether the entire object or just the value is submitted when an option is selected.

(Configured in Datasource Properties)

• modelValue - Identifies which field in the API response contains the value to be submitted when an option is selected.
• modelDisplayValue - Identifies which field in the API response contains the text to display for each option.

Styling

(Configured in Visual Properties)

• placeholderTranslations - Sets the placeholder text displayed when no option is selected, with support for multiple languages.
• showClearIcon - Determines whether to display an icon that allows users to clear the current selection.

Actions & Variants

Actions

(Configured in Event Actions)

• events - Configures the events that the component can trigger and respond to.
• ON_VALUE_CHANGE - Triggered when the user selects a different option.
• ON_INIT_BASED_ON_USER_VIEW - Triggered specifically when the component initializes in user view mode rather than edit mode.
• ON_INIT - Triggered when the dropdown component is initialized.
• ON_DESTROY - Triggered when the component is removed from the DOM.

Variants

(Configured in Visual Properties)

• hidden - Controls whether the component is visible in the form.
• disabled - Controls whether the dropdown can be interacted with by users.
• readonly - Controls whether the selection can be changed by users.

Validation

(Configured in Validation Properties)

• validation - Configures validation rules for the single select dropdown.
• required - When set to true, an option must be selected before the form can be submitted.

Authorization

(Configured in Authorization Properties)

• authorizationDisable - Specifies a policy set that determines when the component should be disabled based on user permissions.

Guidelines

Usage

• Use when exactly one value must be selected; enforce completion with required: true.
• Provide a meaningful, localized prompt by setting placeholderTranslations (e.g., “Select status”).
• Establish predictable state: set initValue for first render and defaultValue for form resets.
• Persist a user’s last choice across sessions with saveInLocalStorage when appropriate.

States & Feedback

• Prevent interaction when unavailable with disabled.
• Show a fixed, visible value that cannot be changed using readonly.
• Only show a clear action when an empty state is valid using showClearIcon.

Data-Driven / Conditional Behavior

• Control loading strategy for large datasets with pageSize; fetch all at once only when appropriate using loadAll.
• Decide emitted payload shape with emitObject (scalar value vs. full option object).

Visibility & Authorization

• Keep the control visible but non-interactive per policy using authorizationDisable.
• Remove the control’s visual footprint (while retaining structure) with hidden.

Content & Localization

• Localize placeholder text via placeholderTranslations; keep phrasing short and action-oriented.
• Ensure option text is human-readable by mapping modelDisplayValue correctly.

Dos & Don’ts

Accessibility

• Announce meaningful guidance by localizing the placeholder with placeholderTranslations.
• Communicate availability accurately: use disabled when interaction isn’t allowed; use readonly when the value must remain visible but fixed.
• Prevent accidental blank submissions by configuring validation with required where a choice is mandatory.
• Expose an explicit clear affordance only when an empty state is valid using showClearIcon.
• Respect permission states by disabling the control via authorizationDisable instead of hiding essential information.
• Display human-readable text by mapping modelDisplayValue to the correct label field.
• Provide predictable behavior for assistive tech by defining initValue and defaultValue.
• Reduce cognitive load in long lists by paginating with pageSize and reserving loadAll for short lists.