Component | Multi Select

Render a multi select dropdown.

Node.js

ui.multiSelectBox("multi-select-input-key", ["A", "B", "C", "D"], { 
    label: "Select options",
    onChange: (values) => console.log(values) // e.g. ["A", "B"]
})

Python

ui.multi_select_box(
    "multi-select-input-key",
    ["A", "B", "C", "D"],
    label="Select options",
    on_change=lambda values: print(values) # e.g. ["A", "B"]
)

Learn more about working with inputs.

Options

Select components support both a "basic" and "detailed" format for options.

Node.js

Python

Basic

Quick and easy. Pass an array of strings, such as ["A", "B", "C", "D"].

Node.js

ui.multiSelectBox("multi-select-input-key", ["A", "B", "C", "D"], { 
    label: "Select options",
    onChange: (values) => console.log(values)
})

Python

ui.multi_select_box(
    "multi-select-input-key",
    ["A", "B", "C", "D"],
    label="Select options",
    on_change=lambda values: print(values)
)

Detailed

Node.js

Use separate label and value fields for each option. The label field will be displayed to the user, and the value field will be passed to hooks such as onChange and validate.

const options = [
    { label: "Google", value: "GOOG" },
    { label: "Apple", value: "APPL" },
    {
        label: "Microsoft",
        value: "MSFT",
        // The detailed format also supports an optional "description" field
        // to display beneath an option.
        description: "Current stock price: $423"
    }
]

ui.multiSelectBox("companies-key", options, {
    label: "Select companies",
    onChange: (values) => console.log(values) // e.g. ["GOOG", "APPL"]
})

Python

Use separate label and value fields for each option. The label field will be displayed to the user, and the value field will be passed to hooks such as on_change and validate.

options = [
    { "label": "Google", "value": "GOOG" },
    { "label": "Apple", "value": "APPL" },
    {
        "label": "Microsoft",
        "value": "MSFT",
        # The detailed format also supports an optional "description" field
        # to display beneath an option.
        "description": "Current stock price: $423"
    }
]

ui.multi_select_box(
    "companies-key",
    options,
    label="Select companies",
    on_change=lambda values: print(values) # e.g. ["GOOG", "APPL"]
)

Detailed option object properties

Node.js

label

required string

The user-facing label to use for the option.

Python

label

required str

The user-facing label to use for the option.

---

Node.js

value

required string | number | boolean

The internal value to assign to the option and use when submitting a form or executing callbacks such as onChange.

Python

value

required str | float | int | bool

The internal value to assign to the option and use when submitting a form or executing callbacks such as on_change.

---

Node.js

description

optional string

Helpful text to display beneath the label.

Python

description

optional str

Helpful text to display beneath the label.

---

API reference

Function signature

Node.js

type OptionValue = string | number | boolean

type DetailedOption = {
    label: string,
    value: OptionValue,
    description?: string
}

ui.multiSelectBox(
    id: string,
    options: Array<OptionValue | DetailedOption>,
    properties: Partial<{
        label: string,
        description: string,
        required: boolean,
        initialValue: DetailedSelectValue,
        validate: (values: Array<DetailedSelectValue>) => string | void,
        onChange: (values: Array<DetailedSelectValue>) => void,
        minSelections: number,
        maxSelections: number,
        style: Style
    }>
)

Python

OptionValue = str | float | int | bool

class DetailedOption(TypedDict):
    label: str
    value: OptionValue
    description: NotRequired[str]

ui.multi_select_box(
    id: str,
    options: list[OptionValue | DetailedOption],
    *,
    label: str | None = None,
    description: str | None = None,
    required: bool = True,
    initial_value: list[DetailedSelectValue] = None,
    validate: Callable[[list[DetailedSelectValue]], str | None] = None,
    on_change: Callable[[list[DetailedSelectValue]], None] = None,
    min_selections: int = 0,
    max_selections: int = 1000000000,
    style: Style | None = None
)

Parameters

Node.js

id

required string

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

Python

id

required str

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

---

Node.js

options

required Array<OptionValue | DetailedValue>

The list of options that can be selected. See the options section for more info.

Python

options

required list[OptionValue | DetailedValue]

The list of options that can be selected. See the options section for more info.

---

Node.js

properties.label

optional string

The label to display above the multiselect box. If not provided, the label will be inferred from the id.

Python

label

optional str

The label to display above the multiselect box. If not provided, the label will be inferred from the id.

---

Node.js

properties.description

optional string

A description to display between the label and multiselect box.

Python

description

optional str

A description to display between the label and multiselect box.

---

Node.js

properties.required

optional boolean

Validate that the multiselect box is not empty before submitting the form it's part of or calling it's onChange hook. Defaults to true.

Python

required

optional bool

Validate that the multiselect box is not empty before submitting the form it's part of or calling it's on_change hook. Defaults to True.

---

Node.js

properties.initialValue

optional Array<string | number | boolean>

The initial value of the multiselect box. Defaults to [] (empty list).

Python

initial_value

optional Array<str | float | int | bool>

The initial value of the multiselect box. Defaults to [] (empty list).

---

Node.js

properties.validate

optional (value: Array<string | number | boolean>) => string | void

Validate the multiselect value before submitting it. If the function returns a string, it will be displayed as an error message.

Python

validate

optional Callable[[Array<str | float | int | bool>], str | None]

Validate the multiselect value before submitting it. If the function returns a string, it will be displayed as an error message.

---

Node.js

properties.onChange

optional (value: Array<string | number | boolean>) => void

A callback function that is called when the user changes the value of the multiselect.

Python

on_change

optional Callable[[Array<str | float | int | bool>], None]

A callback function that is called when the user changes the value of the multiselect.

---

Node.js

properties.minSelections

optional number

Validate that the user has selected at least some number of options. Defaults to 0.

Python

min_selections

optional int

Validate that the user has selected at least some number of options. Defaults to 0.

---

Node.js

properties.maxSelections

optional number

Validate that the user has selected at most some number of options. Defaults to 1000000000.

Python

max_selections

optional int

Validate that the user has selected at most some number of options. Defaults to 1000000000.

---

Node.js

properties.style

optional Style

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.

Python

style

optional Style | None

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.

---