UI API

Use ToolboxUi for dialogs or popups, and UiPage + UiField for custom pages. We suggest using StateFlow-driven pages and keeping UI logic on the provider side when possible.

ToolboxUI

Check the following Kotlin example:

            val ui = serviceLocator.getService<ToolboxUi>()
            val lsf = serviceLocator.getService<LocalizableStringFactory>()
            ui.showWindow()
            ui.showUiPage(MySettingsPage(lsf))
            val confirmed = ui.showYesNoPopup(lsf.ptrl("Delete env"), lsf.ptrl("Are you sure?"),
            lsf.ptrl("Yes"), lsf.ptrl("No"))
        

Use the following best practices:

Refrain from using runBlocking in UI-related code.
Popups are suspending; call from coroutines.
Use LocalizableStringFactory for all user-facing text.

ToolboxUI Components

Use the following components:

showWindow()
showUiPage(page), hideUiPage(page)
Popups (suspending):
- showInfoPopup(header, text|body, okText)
- showErrorInfoPopup(error)
- showYesNoPopup(...), showOkCancelPopup(...)
- showTextInputPopup(header, text, initialText, textType, okText, cancelText)
- showSnackbar(id, header, text, actionLabel) → Boolean

All text uses LocalizableString.

UiPage

Check the following example with validations and actions:

                class MySettingsPage(private val l: LocalizableStringFactory) : UiPage(MutableStateFlow(l.ptrl("Settings"))) {
                  private val _fields = MutableStateFlow<List<UiField>>(emptyList())
                  override val fields: StateFlow<List<UiField>> get() = _fields
                  private val nameField = TextField(l.ptrl("Name"), textType = TextType.PLAIN)
                  private val saveAction = RunnableActionDescription(l.ptrl("Save")) {
                  // save settings
                  }
                  init {
                    nameField.validation = { text -> if (text.isBlank()) ValidationResult.Error(l.ptrl("Name required"))
                    else ValidationResult.Ok }
                    _fields.value = listOf(nameField, ValidationErrorField(nameField), CallToActionField(saveAction))
                  }
                  override val actionButtons = MutableStateFlow(listOf(saveAction))
                  override val defaultButton = MutableStateFlow<ActionDescription?>(saveAction)
                }
            

Use the following components:

titleFlow: StateFlow<LocalizableString>; fields: StateFlow<List<UiField>>
Optional: iconResource, description, isBusy, isBusyCreatingNewEnvironment, highlightElementId, isCancellable, cancel()
Actions: actionButtons: StateFlow<List<ActionDescription>>, defaultButton: StateFlow<ActionDescription?>
Lifecycle: beforeShow(), afterHide(), setActionErrorNotifier(...)

UiField

Use the following components:

Do not implement directly; Use particular components, that are subclasses of BaseUiField
Common properties: visibility: StateFlow<Boolean>, modifiers: StateFlow<List<FieldModifier>>

Components (non-exhaustive)

Use the following components:

LabelField, TextField(textType), LinkField, ActionLinkField
CheckboxField, RadioButtonGroupField, ComboBoxField, RichComboBoxField(V2)
SectionFieldd , RowGroup
Validation, ValidatableField, ValidationResult, ValidationErrorField
AccountDropdownField

08 September 2025