Select New

The Select element lets users pick from a list of options in either single-select or multi-select mode. It supports simple lists or complex objects, custom mapping for labels and values, optional icons or images, keyboard navigation, and an optional search bar.

Features

• Single or multiple selection: Choose one value or many using Type
• Flexible data mapping: Map label, value, icon, image, and disabled from your data
• Searchable options: Enable a search input and choose which fields to search
• Keyboard accessible: Navigate with arrow keys, select with Enter, close with Escape
• Rich option display: Show plain text, icon + text, or image + text
• Chips for multiselect: Selected items display as removable chips in the trigger
• Form-friendly: Works with Required, Field name, and custom validation

Getting started

Using AI

The quickest way to set up a select is by using AI:

1. Ask AI to add the select. Make sure to specify:

   • whether it’s single or multiple
   • your data source (array or collection) for Options
   • mapping for label and value (and icon/image if desired)
   • if Search should be enabled and which fields to search

2. The AI will create a styled select bound to your data.

3. Continue refining your select by asking:

   • "Set Type to multiple and show chips with rounded corners"
   • "Enable search and search by name and email"
   • "Use imageText and map image from my avatar field"

Manual setup

1. Add the Select element to your page from the Add panel
2. In Settings, set Type to single or multiple
3. Provide Options:
   • bind to an array/collection, or
   • use a static array like [{ label: "Option 1", value: "opt1" }, { label: "Option 2", value: "opt2" }]
4. Configure mapping:
   • Label per item → path/formula for the display text
   • Value per item → path/formula for the stored value
   • (optional) Icon per item / Image per item / Disabled condition per item
5. (optional) Enable Search and set Search by to choose which fields are searchable
6. (optional) Set Initial value (single) or Initial value (Multi)
7. Adjust styling in the Style panel for the trigger, dropdown, options, chips, search, and empty state

Option types and mapping

The select can display options in three ways, controlled by Option type:

• text: shows only the option label
• iconText: shows an icon next to the label (map icon)
• imageText: shows an image next to the label (map image)

When your Options are dynamically bound, you can map these fields:

• Label per item
• Value per item
• Icon per item
• Image per item
• Disabled condition per item

TIP

Disabled condition per item lets you programmatically disable specific options. Return true to disable that option (it won’t be clickable and will show disabled styling). This is useful for preventing selection based on status, quotas, or permissions.

Single vs multiple selection

• Set Type to single for one value, or multiple for many values
• In multiselect, selected items display as chips inside the trigger
• Use Select on click and Unselect on click to define selection behavior
• Close on select controls whether the dropdown closes after choosing
• (optional) Limit caps the number of selections in multiselect

Searching options

Enable Search to show a search field at the top of the dropdown.

• Search by: choose fields to search (for object options)
• Auto focus: focuses the search field when the dropdown opens
• Search placeholder: customize the search input placeholder

Keyboard and accessibility

• Arrow Down/Up: open and move focus through options
• Enter: select/unselect the focused option
• Escape: close the dropdown
• ARIA roles and attributes are applied for screen reader support (combobox, listbox, aria-activedescendant, etc.)

Positioning and sizing

• Offset X / Offset Y: shift the dropdown relative to the trigger
• Z-index when open: ensure the dropdown sits above surrounding UI
• Dropdown width and Max-height: control dropdown size (width can follow the trigger by default)

Form integration

• Required: marks the field as required
• Field name: the name used on form submission
• Custom validation + Validation: provide your own validation logic
• The element exposes a value variable (single: any, multiple: array) that you can send to your backend

Example use cases

Country selector (single)

1. Set Type to single
2. Bind Options to an array of country names
3. Set Placeholder to "Select a country"
4. Optionally enable Search and search by the label

Tags input (multiple)

1. Set Type to multiple
2. Bind Options to your tags collection ([{ label, value }])
3. Enable Unselect on click so clicking a selected chip removes it
4. Limit to 5 using Limit

People picker with avatars (image + text)

1. Set Option type to imageText
2. Map Image per item to your avatar field and Label per item to name
3. Enable Search and search by name and email

Payment method with icons (icon + text)

1. Set Option type to iconText
2. Map Icon per item based on your icon code and Label per item to the method name
3. Mark certain options as disabled with Disabled condition per item

Best practices

Do:

• keep Value per item stable (e.g., IDs) to avoid mismatches
• use Close on select for single-select to reduce clicks
• enable Search for long lists and define clear Search by fields

Don't:

• close the dropdown after each pick in multiselect when users need to select many
• leave Search off for long lists where users must find items quickly
• enable Manual trigger without wiring actions to open/close the dropdown

Forking

While the Select element offers extensive built-in customization options, there may be cases where you need functionality beyond what's natively available. In these situations, you can fork the element and modify it to meet your specific requirements.

If you are unsure how to fork an element, you can learn more in the dedicated documentation @Learn more about generating custom coded components →

Forking example: custom chip layout

One reason to fork the Select would be to add custom chip content/layout (e.g., secondary text or a status dot) that isn’t part of the base element.

Please fork the Select element and add support for chips with a secondary line of text and a small status dot on the left.

This would let you render additional data inside selected chips while keeping the rest of the control unchanged.

Properties reference

Settings

Property	Options/Type	Description
Option type	text/iconText/imageText	How each option is displayed
Options	Collection/Array	List of options (objects or primitives)
Label per item	Formula	Returns the label for an option
Icon per item	Formula	Returns the icon code (when using iconText)
Image per item	Formula	Returns the image URL (when using imageText)
Value per item	Formula	Returns the stored value for an option
Disabled condition per item	Formula	Returns true to disable an option
Type	single/multiple	Choose single or multiple selection
Initial value (single)	Text/Array	Default selected value (string or array; first value used)
Initial value (Multi)	Array	Default selected values for multiselect
Placeholder	Text	Trigger placeholder when no selection
No results text	Text	Empty state text when search returns no results
Search placeholder	Text	Placeholder shown in the search input
Initial state	closed/open	Open the dropdown on load if set to open
Close on select	Boolean	Close the dropdown after selecting
Close on click outside	Boolean	Close when clicking outside
Manual trigger	Boolean	Disable click-to-open; control with actions
Disabled	Boolean	Prevent user interaction
Required	Boolean	Mark the field as required (forms)
Read-only	Boolean	Show value but prevent changes
Allow scrolling when open	Boolean	Allow page scrolling while dropdown is open
Select on click	Boolean	Select when clicking an option
Unselect on click	Boolean	Unselect when clicking a selected option
Limit	Number	Max number of selections (multiselect)
Search	Boolean	Show a search input above options
Search by	Array	Fields to search (e.g., [ { filter: "['name']" } ])
Auto focus	Boolean	Focus the search input when opening
Field name	Text	Name to use for form submission
Custom validation	Boolean	Enable a custom validation formula
Validation	Formula	Custom validation logic when enabled

Styling

Selected (single)

Property	Description
Font family	Font family for the selected text
Font size	Size of selected text
Font weight	Weight of selected text
Font color	Color of selected text
Padding	Inner spacing around selected text
Text align	Text alignment in the trigger

Placeholder

Property	Description
Font family	Font for placeholder
Font size	Placeholder size
Font weight	Placeholder weight
Font color	Placeholder color
Text align	Placeholder alignment

Chip (multiple)

Property	Description
Font family/size/weight/color	Chip text appearance
Padding	Chip inner spacing
Background color	Chip background
Border / Borders (split/all)	Chip border styling
Border radius	Chip corner rounding
Unselect icon	Icon used to remove a chip
Icon color/size	Unselect icon appearance
Image size/radius	Chip image settings (with imageText)

Trigger

Property	Description
Height	Trigger height
Borders / Border (split or all sides)	Trigger border styling
Border radius	Trigger corner rounding
Background color	Trigger background
Shadows	Trigger shadow
Padding / Margin	Trigger spacing
Open icon / Close icon	Icons for the trigger state
Icon color/size	Trigger icon appearance
Image size/radius	Trigger image appearance (single + imageText)

Dropdown

Property	Description
Width	Dropdown width (defaults to trigger width)
Max-height	Max dropdown height (scrolls inside)
Borders / Border (split or all sides)	Dropdown border styling
Border radius	Dropdown corner rounding
Background color	Dropdown background
Shadows	Dropdown shadow
Padding	Inner spacing
Z-index when open	Stacking context while open
Offset X / Offset Y	Position offset relative to trigger

Option

Property	Description
Font family/size/weight/color	Option text appearance
Spacing	Gap between options
Padding	Option padding
Border	Option border
Border radius	Option corner rounding
Background	Default background
Hover background	Background on hover
Focus background	Background when focused via keyboard
Cursor	Cursor style
Checked icon / color / size	Icon shown for selected options
Image size / radius	Image appearance (with imageText)

Empty state

Property	Description
Font family/size/weight/color	Empty-state text styling
Padding	Empty-state padding
Text align	Empty-state alignment

Search

Property	Description
Width / Height	Search input size
Border(s) / Radius	Search input border styling
Padding / Margin	Search input spacing
Outline / Offset	Outline styling
Font family/size/weight/color	Search text styling
Background color	Search input background
Placeholder color	Search placeholder color

Component actions

Action	Description	Parameters
Open	Opens the dropdown	—
Close	Closes the dropdown	—
Toggle	Toggles open/closed	—
Set value	Sets the current value	value: any (array accepted; single uses first item)
Reset value	Resets to initial value	—
Remove specific value (multiselect)	Removes one selected value	value: any
Reset search	Clears the search input	—
Focus	Focuses the trigger	—

Exposed variables

Variable	Type	Description
value	Any/Array	The current selection (single: any; multiple: array)

Example variable values

value (single)

"opt1"

value (multiple)

["opt1", "opt3"]

Select local context (advanced)

When building inside the element’s local context, you can access:

• options: array of { value, label, disabled, isSelected, data }
• active: { value, details } where value is the current selection and details includes resolved label/icon/image
• utils: { type, isOpen, triggerWidth, triggerHeight }
• search (when enabled): { value, searchBy, searchMatches }

Event triggers

Event	Description	Payload
On change	Fired when selection changes	{ value } (single: any, multiple: any[])
On init value change	Fired when initial value is applied/changes	{ value }
On focus	Fired when the element gains focus	{}
On blur	Fired when the element loses focus	{}

Example event payloads

On change (single)

{ "value": "opt1" }

On change (multiple)

{ "value": ["opt1", "opt3"] }

On init value change

{ "value": ["opt2"] }

Frequently asked questions

How do I bind object options and map fields?

Bind Options to your array of objects. Then set:

• Label per item to the display text field (e.g., context.mapping['name'])
• Value per item to a stable identifier (e.g., context.mapping['id'])
• (optional) Icon per item or Image per item
• (optional) Disabled condition per item to a boolean formula

How do I enable and configure search?

Toggle Search to On. In Search by, add entries like { filter: "['name']" } for each field. Set Auto focus if you want the search to focus when opened.

What does "Manual trigger" do?

When Manual trigger is On, clicking the trigger doesn’t open the dropdown. Use the actions Open, Close, or Toggle to control it programmatically.

How can I limit the number of selections?

When using multiselect, set Limit to a number. Additional selections are ignored once the limit is reached.

How do I integrate with forms?

Set Field name, choose whether it’s Required, and optionally enable Custom validation with your Validation formula. Submit the exposed value to your backend.