Multiselect

A combination select and input field to select multiple values or directly enter them as text. It supports custom value entries to allow values outside those provided, and can perform validation of required field, minimum or maximum length, and custom rules.

Properties

Available properties for Multiselect with supported data types or values. You can write JavaScript almost anywhere in Retool to manipulate or read information about components.

NameTypeDescriptionvalue(string | number | boolean | null | undefined)[]

The current value.

allowCustomValueboolean

Whether to allow custom values that do not already exist in values.

automaticItemColorsboolean

Whether to automatically assign a color to each item.

captionByIndexstring[]

A list of captions for each item, by index.

colorByIndexstring[]

A list of colors for each item, by index.

data{ [key: string]: unknown }[]

The source data for the component.

disabledboolean

Whether user input, interaction, or selection is disabled.

disabledByIndexboolean[]

A list of boolean values for each item, by index, that reflect whether they are disabled.

disabledValues(string | number | boolean | null | undefined)[]

A list of values not available for selection.

emptyMessagestring

The message to display if no value is set.

fallbackTextByIndexstring[]

A list of values to use as fallback text for each option. Only the first two characters are displayed. If multiple words are provided, the first letter of each word is used.

formDataKeystring

The key used by a Form component to assign default values to input fields using form.initialData, and to construct the form.data property.

hiddenboolean

Whether the component is visible.

hiddenByIndexboolean[]

A list of boolean values for each item, by index, that reflect whether they are hidden.

hideValidationMessageboolean

Whether to hide the validation message if the invalid is true.

iconAfterIconKey

The icon to display after the primary content.

iconBeforeIconKey

The icon to display before the primary content.

iconByIndexIconKey[]

A list of icons for each item, by index.

imageByIndexstring[]

A list of images for each item, by index.

inputValuestring

The current or most recently entered value of the input field.

invalidboolean

Whether the current value has failed any validation rules.

itemAdornmentShape'circle' | 'square'

The adornment shape.

itemAdornmentSize'auto' | 'small' | 'large'

The adornment size.

itemMode'dynamic' | 'static'

The configuration mode for option lists. Either dynamic for mapped options or static for manual options.

labelstring

The text to display as a label for the input field.

labelAlign'left' | 'right'

The horizontal alignment of the label.

labelCaptionstring

The additional text to display with the label.

labelPosition'left' | 'top'

The position of the label relative to the input field.

labelWidthnumber

The label width, in the unit specified in labelWidthUnit.

labelWidthUnit'%' | 'px' | 'col'

The specified units for labelWidth.

labelWrapboolean

Whether the label can wrap to multiple lines.

labelsstring[]

A list of labels for each item. Falls back to the corresponding value if no label is provided.

loadingboolean

Whether to display a loading indicator.

maintainSpaceWhenHiddenboolean

Whether the component takes up space on the canvas if hidden is true.

marginstring

The amount of margin to render outside of the component.

maxCountnumber | null

The maximum number of items to allow.

maxLinesnumber | null

The maximum number of lines of text to display if wrapTags is true.

minCountnumber | null

The minimum number of items to allow.

minLinesnumber | null

The minimum number of lines to display.

overlayMaxHeightnumber | null

The maximum height of the dropdown, in px.

overlayMinWidthnumber | null

The minimum width of the dropdown, in px.

persistSearchTermboolean

Whether the input value is retained after selecting an option.

placeholderstring

The text to display in the input field when empty.

readOnlyboolean

Whether the value is read only and cannot be modified.

requiredboolean

Whether the input is required for validation.

searchMode'fuzzy' | 'disabled' | 'caseSensitive' | 'caseInsensitive'

The type of search to perform.

selectedIndexesnumber[]

A list of currently selected values, by index.

selectedItemsunknown[]

A list of currently selected items.

selectedLabelsstring[]

A list of labels for currently selected values, by index.

showClearboolean

Whether to display a button to clear the current value of the input field.

showInEditorboolean

Whether the component remains visible in the editor if hidden is true.

showSelectionIndicatorboolean

Whether to display an icon next to a selected item.

textAfterstring

The text to display after the primary content.

textBeforestring

The text to display before the primary content.

tooltipByIndexstring[]

A list of tooltips for each item, by index.

tooltipTextstring

The text to display in a tooltip on hover or focus.

validationMessagestring

The validation message to display if the input is invalid.

values(string | number | boolean | null | undefined)[]

A list of possible values.

wrapTagsboolean

Whether tags wrap to multiple lines.

deprecatedLabelsDeprecatedstring[]

Events

Events are triggered by user interactions with Multiselect. Use event handling to trigger queries or other actions in response to events.

NameDescriptionChange

A user changes the current value.

Blur

A user deselects the input field.

Focus

A user selects the input field.

Input value change

A user changes the current value of the input field.

Methods

Methods for interacting with Multiselect. You can write JavaScript almost anywhere in Retool and use methods to manipulate data or components.

NameDescriptionsetValue(value: any)

Set the current value.

clearValue()

Clear the current value.

scrollIntoView(options: any)

Scrolls the canvas or parent container so that the selected component appears in the visible area.

validate()

Validates the value of the input field.

clearValidation()

Clear the validation message from the input field.

setHidden(hidden: boolean)

Set the hidden value to toggle whether the component is visible. Defaults to true without a parameter.

setDisabled(disabled: boolean)

Set the disabled value to toggle whether the input field is disabled. Defaults to true without a parameter.

resetValue()

Reset value to the default value.

focus()

Set focus on the input field.

Related components