> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi select

> The Multi Select form field is an element that allows users to choose multiple options from a list of choices. Each option consists of a label, which is displayed in the dropdown menu, and a corresponding value, which is stored upon selection.

<Frame>
  ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
</Frame>

<Info>
  For example, consider a scenario where you have options "Sports" with the value "S", "Music" with the value "M", and "Reading" with the value "R". When a user selects both "Sports" and "Music" in the process instance, the values \["S", "M"] will be stored as an array for the "Multi Select" key.
</Info>

## Configuring the Multi Select element

### Multi Select generic settings

These allow you to customize the generic settings for the Multi Select element:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource-configuration)
* [**Validators**](#validators)
* [**Expressions**](#expressions)
* [**Event handlers**](#event-handlers)
* [**Multi Select styling**](#multi-select-styling)

#### Process data key

Process data key establishes the binding between the multi select element and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node#from-integration).

<Note>
  The Multi Select component stores selected values as an array, similar to how a Checkbox works. This differs from the single Select component, which stores only a single value.
</Note>

#### Properties

* **Label**: The visible label for the multi select element.
* **Placeholder**: Text that appears within the multi select element when it is empty.
* **Empty message**: Text displayed for custom type when no results are found.
* **Helpertext**: Additional information about the multi select element, which can be optionally hidden within an infopoint.
* **Show selections**: Controls how selected items are displayed. Available display modes:
  * **Comma separated**: Selected values are displayed as a comma-separated text string within the input field (e.g., "Option 1, Option 2, Option 3")
  * **Chips inside**: Selected values appear as chips/badges inside the input field, allowing individual removal with close buttons
  * **Chips outside**: Selected values are displayed as chips/badges below the input field, keeping the input area clean
* **Max. Options Selectable**: Sets the maximum number of options that can be selected simultaneously.

#### Show selections display modes

The "Show selections" property determines how users see their selected options. Each mode offers different benefits depending on your use case:

<Tabs>
  <Tab title="Comma separated">
    Selected values are displayed as a comma-separated text string within the input field. This mode is space-efficient and works well when you have predictable option lengths.

    **Best for:** Simple lists, short option names, read-only display scenarios

    <Frame>
      ![Multi Select with comma separated display](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ms1.png)
    </Frame>
  </Tab>

  <Tab title="Chips inside">
    Selected values appear as individual chips/badges inside the input field with close buttons `×` for easy removal. This mode provides clear visual separation and allows users to remove specific selections easily.

    **Best for:** Interactive forms, when individual item removal is important, moderate number of selections

    <Frame>
      ![Multi Select with chips inside display](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ms2.png)
    </Frame>

    **Features:**

    * Individual close buttons for each selection
    * Clear visual distinction between options
    * Hover effects for better interaction
  </Tab>

  <Tab title="Chips outside">
    Selected values are displayed as chips/badges below the input field, keeping the input area clean and uncluttered. This mode is ideal when you expect many selections or longer option names.

    **Best for:** Forms with many selections, long option names, when input field clarity is important

    <Frame>
      ![Multi Select with chips outside display](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ms3.png)
    </Frame>

    **Benefits:**

    * Input field remains clean and readable
    * Better accommodation for many selections
    * Improved mobile experience with long lists
  </Tab>
</Tabs>

<Tip>
  **Choosing the right display mode:**

  * Use **comma separated** for simple, read-only scenarios or when space is limited
  * Use **chips inside** for interactive forms where users frequently add/remove items
  * Use **chips outside** for complex forms with many selections or when input field clarity is crucial
</Tip>

#### Datasource configuration

* **Default value**: Autofill the multi select field with these values. You need to specify an array of values from the value/label pairs defined in the Datasource tab.

<Frame>
  ![Multi Select default value configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
</Frame>

* **Source Type**: The source can be Static, Enumeration, or Process Data.
* **Add option**: Define label and static value pairs here.

#### Process Data

When the data source type is set to Process Data, the multi select element will be populated with options from a specific process data key. This approach provides dynamic data loading capabilities, allowing options to be generated, modified, or filtered at runtime through business rules.

#### Configuration steps

* Set Source Type: Select "Process Data" from the Source Type dropdown
* Specify Process Data Key: Enter the key path where your options array is stored (e.g., app.options)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/br_multi.png)
</Frame>

Example of JavaScript business rule that populates the multi select element with the values from the process data key:

```javascript theme={"system"}
options = [
    {
        "label": "option 1",
        "value": "option1",
        "enabled": true
    },
    {
        "label": "option 2",
        "value": "option2",
    },
    {
        "label": "option 3",
        "value": "option3",
        "enabled": false
    },
    {
        "label": "option 4",
        "value": "option4",
        "enabled": false
    },
    {
        "label": "option 5",
        "value": "option5"
    }
];

output.put("app", {"options": options});
```

Now the multi select element will be populated with the values from the `app.options` key:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_data_multiselect.png)
</Frame>

#### Validators

You can add multiple validators to a multi select field. For more details, refer to [**Validators**](../../validators).

Common validators for Multi Select include:

* **Required**: Ensures at least one option is selected
* **Custom**: You can add a custom validator to the multi select element.
* **Custom Expression**: You can add a custom expression to the multi select element.

#### Hide/disable expressions

The multi select field's behavior can be defined using JavaScript expressions for hiding or disabling the element. The following properties can be configured for expressions:

* **Hide condition**: A JavaScript expression that hides the Multi Select field when it returns a truthy value.
* **Disabled condition**: A JavaScript expression that disables the Multi Select field when it returns a truthy value.

<Info>
  It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.
</Info>

#### Event handlers

Event handlers can be added to the multi select element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the type of the action to be performed.

<Info>
  For more information, see the [Event Handlers documentation](../../event-handlers).
</Info>

### Disabled options

You can control the availability of specific options in Multi Select elements by marking them as disabled. This feature is particularly useful for implementing business logic that restricts certain choices based on user permissions, subscription levels, or contextual conditions.

#### Example

<Note>
  The `enabled` property is used to control the availability of the option.
</Note>

```javascript theme={"system"}
options = [
    {
        "label": "option 1",
        "value": "option1",
        "enabled": true
    },
    {
        "label": "option 2",
        "value": "option2",
        "enabled": false
    },
    {
        "label": "option 3",
        "value": "option3",
        "enabled": true
    },
    {
        "label": "option 4",
        "value": "option4",
        "enabled": false
    },
    {
        "label": "option 5",
        "value": "option5"
    },

    
];

output.put("app", {"options": options});
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/disabled_options.png)
</Frame>

### Multi Select settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

### Web overrides

* Properties:
  * **Label**: Override the multi select label.
  * **Helper**: Override helper text/info point.
  * **Placeholder**: Override the placeholder.
  * **Show selections**: Override the show selections.
* Expressions:
  * **Hide**: Override the hide expression.

### iOS overrides

Same as Web overrides.

### Android overrides

Same as Web overrides.

<Tip>
  Overrides can always be imported/pushed from one platform to another:

  ![Importing and pushing overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)
</Tip>

### Multi Select styling

<Tabs>
  <Tab title="Web">
    <Tabs>
      <Tab title="Max Rows">
        * **Max Rows**: Adjust the maximum number of rows of the multi select element.
      </Tab>

      <Tab title="Spacing">
        * **Margin**: Adjust the margin of the multi select element.
        * **Padding**: Adjust the padding of the multi select element.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="iOS">
    Similar styling considerations apply to iOS as for web.

    However, for mobile applications, there's an additional sizing style property specific to multi select elements:

    * **Fit Width**: Adjust the fit width of the multi select element:
      * **fill**: Fills the available space.
      * **fixed**: Maintains a fixed width.
      * **auto**: Adjusts the width automatically based on content.
  </Tab>

  <Tab title="Android">
    Similar styling considerations apply to Android as for web.

    However, for mobile applications, there's an additional sizing style property specific to multi select elements:

    * **Fit Width**: Adjust the fit width of the multi select element:
      * **fill**: Fills the available space.
      * **fixed**: Maintains a fixed width.
      * **auto**: Adjusts the width automatically based on content.
  </Tab>
</Tabs>

#### Multi Select style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

Style options:

<AccordionGroup>
  <Accordion title="Common Properties">
    * Border radius **\[TEXT]**
    * Border width **\[TEXT]**
    * Text style **\[FONT]**

    <Frame>
      ![Multi Select common properties overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_com_props.png)
    </Frame>
  </Accordion>

  <Accordion title="Label">
    * Default state
      * Text color **\[COLOR]**
    * Disabled state
      * Text color **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![Multi Select label overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_label.png)
    </Frame>
  </Accordion>

  <Accordion title="Helper">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**
    * Helper Tooltip
      * Text style **\[FONT]**
      * Text color **\[COLOR]**
      * Background color **\[COLOR]**
      * Icon Color **\[COLOR]**

    <Frame>
      ![Multi Select helper overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_helper.png)
    </Frame>
  </Accordion>

  <Accordion title="Error">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![Multi Select error overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_error.png)
    </Frame>
  </Accordion>

  <Accordion title="Empty State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![Multi Select empty state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_empty_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Active State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![Multi Select active state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_active_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Filled State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**
    * Selected chip background **\[COLOR]**
    * Selected chip text color **\[COLOR]**
    * Selected chip border color **\[COLOR]**

    <Frame>
      ![Multi Select filled state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_filled_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Disabled State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![Multi Select disabled state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_disabled_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Error State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![Multi Select error state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_error_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Hover State (only for Web configuration)">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![Multi Select hover state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_hover_state.png)
    </Frame>
  </Accordion>
</AccordionGroup>

<Info>
  You can import or push the overrides from one platform to another without having to configure them multiple times.

  ![Importing and pushing overrides for Multi Select](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)
</Info>

# Example - Income sources selection form

Let's create an example using **enumeration data** to create an income sources selection form where users can select multiple income sources from a predefined list, as part of a loan application process.

To create this kind of process, we need the following elements:

* a [**user task node**](../../../node/user-task-node) (here we have the client forms and here we add the MULTI SELECT elements)

<Frame>
  ![Multi Select user task configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_process.png)
</Frame>

### Creating the enumeration

First, we need to create an enumeration for income sources:

1. Create it on your project or in a library.
2. Click on the breadcrumbs (top-right corner) then click **New enumeration** (the Enumeration Designer will now open).
3. Create an enumeration named \`\` with the following values:
   * **S** - Salary
   * **F** - Freelance
   * **R** - Rents
   * **I** - Investments

<Frame>
  ![Income sources enumeration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_enum_income.png)
</Frame>

<Frame>
  ![Income sources enumeration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/enum_multi_select.png)
</Frame>

### Configuring the UI

Follow the next steps to configure the UI needed:

1. Select the **user task node** and click the **brush icon** to open [**UI Designer**](../../ui-designer).
2. Add a [**Card**](../root-components/card) UI element as a [**root component**](../root-components/) (this will group the other elements inside it) with the following properties:

* Generic:
  * **Title** - *Loan Application Form*

3. Inside the **card**, add a [**form element**](./).
4. Inside the **form** add the standard form fields (First Name, Last Name, Date of Birth, Email, Income) and then add a **multi select element** for income sources selection.
5. For the multi select element (Income Sources) set the following properties:
   * **Process data key** - `application.incomeSources`

<Info>
  The attribute `application.incomeSources` is the key on which we added income sources selection. It is an array of strings with the source of enumeration.

  <Frame>
    ![Multi Select income sources configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/incomeSource_attr.png)
  </Frame>
</Info>

* **Label** - Income Sources
* **Placeholder** - Select your income sources...
* **Empty message** - No income sources found
* **Show selections** - Comma Separated
* **Max. Options Selectable** - 4 (reasonable limit for income sources)
* **Source type** - Enumeration
* **Enumeration** - Select `incomeSources` from the dropdown

<Frame>
  ![Multi Select income sources configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/incomeSource_dropdown.png)
</Frame>

8. Test and run the process by clicking **Start process**.

<video autoPlay muted loop playsInline src="https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_demo.mp4" />

## Data handling and validation

### Common validation scenarios

<Accordion title="Required income sources validation">
  Ensure at least one income source is selected for loan applications:

  ```javascript theme={"system"}
  // Validator expression
  ${application.incomeSources != null && application.incomeSources.length > 0}
  ```

  **Error message**: "Please select at least one income source to continue with your application."
</Accordion>

<Accordion title="Minimum income diversity validation">
  Require at least 2 different income sources for better loan approval chances:

  ```javascript theme={"system"}
  // Validator expression  
  ${application.incomeSources != null && application.incomeSources.length >= 2}
  ```

  **Error message**: "Please select at least 2 income sources to demonstrate income stability."
</Accordion>

<Accordion title="Maximum income sources validation">
  Limit to maximum 4 income sources to keep the application manageable:

  ```javascript theme={"system"}
  // Validator expression
  ${application.incomeSources == null || application.incomeSources.length <= 4}
  ```

  **Error message**: "Please select no more than 4 primary income sources."
</Accordion>

<Accordion title="Primary income validation">
  Ensure that salary or business income is selected as a primary source (for certain loan types):

  ```javascript theme={"system"}
  // Validator expression
  ${application.incomeSources != null && (application.incomeSources.contains("salary") || application.incomeSources.contains("business"))}
  ```

  **Error message**: "At least one primary income source (Salary or Business Income) is required for this loan type."
</Accordion>

## Best practices

<Check>
  **Limit options**: Don't overwhelm users with too many options. Consider grouping or categorizing if you have many choices.
</Check>

<Check>
  **Set maximum selections**: Use the "Max. Options Selectable" property to prevent users from selecting too many options.
</Check>

<Check>
  **Provide clear labels**: Make option labels descriptive and easy to understand.
</Check>

<Check>
  **Consider mobile experience**: Test how selected items display on mobile devices, especially when many options are selected.
</Check>

<Check>
  **Validate selections**: Always validate that the user's selections meet your business requirements using appropriate validators.
</Check>

<Check>
  **Handle empty states**: Provide clear messaging when no options are available or when search yields no results.
</Check>

## Differences from Single Select

| Feature          | Single Select                       | Multi Select                                  |
| ---------------- | ----------------------------------- | --------------------------------------------- |
| **Selection**    | One option only                     | Multiple options                              |
| **Data Storage** | Single value                        | Array of values                               |
| **Display**      | Selected value                      | Chips, comma-separated, or custom format      |
| **Validation**   | Simple required validation          | Min/max selections, required array validation |
| **Use Cases**    | Country selection, status selection | Skills, categories, tags, interests           |
| **Clear Action** | Clears single selection             | Clears all selections                         |

<Info>
  When migrating from Single Select to Multi Select, remember to update your data model to handle arrays and adjust any business rules or integrations that process the selected values.
</Info>