Combobox

<- Back to Forms Components

Combobox is a single-select option input. It is built on the Select contract with multiple=false and searchable=true.

Contract¶

Property	Type	Notes
`label`	`str`	Input label.
`options`	`list[dict]`	Option entries with `label` and `value`.
`value`	`Any`	Current selected option value.
`placeholder`	`str`	Text shown before a value is selected.
`max_width`	`int \| None`	Optional width constraint.
`action` / `params`	`str` or action object / `dict`	Optional action emitted on change. Action objects can include `confirm`.

Value collected by actions: usually str.

Action Confirmation¶

Use an action object with confirm to require confirmation before the combobox selection action is dispatched. If the user cancels the dialog, no backend action is sent and the combobox keeps its previous value.

The component test page exposes a combobox action counter and the last received payload so dispatch can be checked directly after confirming.

field = sdk.ui.Combobox(
    "confirm_python_combobox",
    label=sdk.i18n.t("components.combobox.confirm.python_label"),
    options=[
        {"label": sdk.i18n.t("components.choice.confirm.option_alpha"), "value": "alpha"},
        {"label": sdk.i18n.t("components.choice.confirm.option_beta"), "value": "beta"},
        {"label": sdk.i18n.t("components.choice.confirm.option_gamma"), "value": "gamma"},
    ],
    value="alpha",
    placeholder=sdk.i18n.t("components.combobox.confirm.placeholder"),
)
field.set_prop(
    "action",
    {
        "name": "components.combobox_confirm_action",
        "context": {"source": "python_combobox"},
        "confirm": {
            "text": sdk.i18n.t("components.combobox.confirm.prompt"),
            "confirm_text": sdk.i18n.t("components.combobox.confirm.accept"),
            "cancel_text": sdk.i18n.t("components.combobox.confirm.cancel"),
        },
    },
)

- kind: Combobox
  id: confirm_yaml_combobox
  label: "@t/components.combobox.confirm.yaml_label"
  value: alpha
  placeholder: "@t/components.combobox.confirm.placeholder"
  options:
    - label: "@t/components.choice.confirm.option_alpha"
      value: alpha
    - label: "@t/components.choice.confirm.option_beta"
      value: beta
    - label: "@t/components.choice.confirm.option_gamma"
      value: gamma
  action:
    name: components.combobox_confirm_action
    context:
      source: yaml_combobox
    confirm:
      text: "@t/components.combobox.confirm.prompt"
      confirm_text: "@t/components.combobox.confirm.accept"
      cancel_text: "@t/components.combobox.confirm.cancel"

Example¶

field = sdk.ui.Combobox(
    "components_test_forms_combobox_store",
    label="Combobox",
    options=[
        {"label": "Rome", "value": "rome"},
        {"label": "Milan", "value": "milan"},
        {"label": "Turin", "value": "turin"},
    ],
    value=bound.store("/components_test/forms/combobox/store", scope="page", default="rome"),
    placeholder="Choose city",
)

- kind: Combobox
  id: components_test_forms_yaml_combobox
  label: "Combobox YAML"
  value: {type: store, scope: page, path: /components_test/forms/combobox/store, default: rome}
  placeholder: "Choose city"
  options:
    - label: "Rome"
      value: rome
    - label: "Milan"
      value: milan
    - label: "Turin"
      value: turin

Runtime¶

Use collect_input_ids to read the selected option value. Combobox is not a free-text field; the output is the selected option value.