# multiple-choice-checklist

## Overview

`multiple-choice-checklist` allows users to select multiple options from a list.

{% hint style="info" %}
**Version compatibility**

`multiple-choice-checklist` was introduced in version **4.36.1** of the JourneyApps Container.

It was updated visually and the `disabled` attribute was introduced in version **4.75.0** of the JourneyApps Runtime.
{% endhint %}

### Basic Example

{% code title="main.view\.xml" %}

```xml
<var name="contact_methods" type="multiple-choice">
    <option key="email">Email</option>
    <option key="sms">SMS</option>
    <option key="Post">Post</option>
</var>

<multiple-choice-checklist label="Preferred Contact Method" bind="contact_methods" />
```

{% endcode %}

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-313ce5e2bf030c3fb87eb5149a5212b927482a73%2Fmultiple-choice-checklist-example.png?alt=media)

## Standard Attributes

### `bind`

{% content-ref url="../xml-fields/bind" %}
[bind](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/bind)
{% endcontent-ref %}

### `label`

{% content-ref url="../xml-fields/label" %}
[label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label)
{% endcontent-ref %}

### `required`

{% content-ref url="../xml-fields/required" %}
[required](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/required)
{% endcontent-ref %}

## Advanced Attributes

### `align-content` <a href="#standard-attributes" id="standard-attributes"></a>

{% content-ref url="../xml-fields/align-content" %}
[align-content](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-content)
{% endcontent-ref %}

### `align-label`

{% content-ref url="../xml-fields/align-label" %}
[align-label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-label)
{% endcontent-ref %}

### `checkbox-position`

{% hint style="info" %}
**Version compatibility**

`checkbox-position` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `left` | `right`

**Default**: `left`

Specify where the checkbox is positioned in the component (relative to the option label).

{% code title="main.view\.xml" %}

```xml
<columns>
    <column>
        <info>checkbox-position="left"</info>
        <multiple-choice-checklist checkbox-position="left" bind="favorite_color" label="Favorite color" />
    </column>
    <column>
        <info>checkbox-position="right"</info>
        <multiple-choice-checklist checkbox-position="right" bind="favorite_color" label="Favorite color" />
    </column>
</columns>
```

{% endcode %}

<figure><img src="https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FnFgRRML6BugJANe7Xqmv%2Fimage.png?alt=media&#x26;token=2ea2ca60-9c64-4c51-94ab-d6ffcdc9f2ce" alt=""><figcaption></figcaption></figure>

### `disabled`

{% hint style="info" %}
**Version compatibility**

`disabled` was introduced in version **4.75.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/disabled" %}
[disabled](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/disabled)
{% endcontent-ref %}

### `id`

{% content-ref url="../xml-fields/id" %}
[id](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id)
{% endcontent-ref %}

### `label-case`

{% hint style="info" %}
**Version compatibility**

`label-case` was introduced in version **4.80.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/label-case" %}
[label-case](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-case)
{% endcontent-ref %}

### `label-color`

{% content-ref url="../xml-fields/label-color" %}
[label-color](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-color)
{% endcontent-ref %}

### `mode`

{% hint style="info" %}
**Version compatibility**

`mode` was introduced in version **4.83.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `row` | `column`

**Default**: `column`

Configure the layout of the list of check box options. `row` lists options horizontally; `column` lists options vertically.

### `modifier-text`

{% content-ref url="../xml-fields/modifier-text" %}
[modifier-text](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/modifier-text)
{% endcontent-ref %}

### `on-change`

{% content-ref url="../xml-fields/on-change" %}
[on-change](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/on-change)
{% endcontent-ref %}

{% hint style="info" %}
When using `multiple-choice-integer` you can omit the key attribute on options. The array passed to the function assigned to `on-change` will correspond to the key starting from `0.` E.g. `[0, 2]` corresponds to first and third options.
{% endhint %}

### `show-if` and `hide-if`

{% content-ref url="../xml-fields/show-if" %}
[show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if)
{% endcontent-ref %}

{% content-ref url="../xml-fields/hide-if" %}
[hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if)
{% endcontent-ref %}

## Component Methods

The following component methods are available when an [`id`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id) is assigned to the component and `component.multipleChoiceChecklist({id:'my-id'})` is called from JS/TS:

### `clear`

Clear the selected option(s) of the `multiple-choice-checklist`.

### `scrollIntoView`

Programmatically scroll until the `multiple-choice-checklist` is visible in the view.

### `selectItem`

Select an item by its label of the list of options of the `multiple-choice-checklist`.

{% code title="main.view\.xml" %}

```xml
<var name="favorite_colors" type="multiple-choice">
    <option key="green">Green</option>
    <option key="red">Red</option>
    <option key="yellow">Yellow</option>
</var>

<multiple-choice-checklist id="my-checklist" bind="favorite_colors" label="Favorite Colors" />

```

{% endcode %}

{% code title="main.js" %}

```javascript
function select() {
    component.multipleChoiceChecklist({id: 'my-checklist'}).selectItem('Yellow');
}
```

{% endcode %}

### `selectItemByIndex`

Select an item by its index of the list of options of the `multiple-choice-checklist`. **Note**: Indexes begin at 1.

{% code title="main.view\.xml" %}

```xml
<var name="favorite_colors" type="multiple-choice">
    <option key="green">Green</option>
    <option key="red">Red</option>
    <option key="yellow">Yellow</option>
</var>

<multiple-choice-checklist id="my-checklist" bind="favorite_colors" label="Favorite Colors" />

```

{% endcode %}

{% code title="main.js" %}

```javascript
function select() {
    component.multipleChoiceChecklist({id: 'my-checklist'}).selectItemByIndex(2);
    // Selects "Red"
}
```

{% endcode %}