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

# Multiple Choice Field

> Multiple selections from predefined options

The Multiple Choice field allows users to select multiple items from a predefined list of options. This field type displays as a checkbox group where users can check any combination of the available options.

Use Multiple Choice fields when you need to collect multiple selections from a fixed set of possibilities — services required, features selected, categories, interests, or any scenario where "select all that apply" is appropriate.

## When to Use

**Use Multiple Choice fields for:**

* Services or products selected
* Features or options enabled
* Categories or tags
* Interests or preferences
* Coverage types or insurance products
* Document types required
* Affected areas or departments
* Applicable regulations or requirements

**Consider alternatives:**

* Use **Choices** for single selection only
* Use **Checkbox** for a single yes/no option
* Use **Text** for free-form input

## Configuration Options

| Option           | Description                   | Type   | Default          | Example                        |
| ---------------- | ----------------------------- | ------ | ---------------- | ------------------------------ |
| `key`            | Unique identifier             | String | Required         | `services_required`            |
| `name`           | Display label                 | String | Required         | "Services Required"            |
| `description`    | Help text for users           | String | Optional         | "Select all services you need" |
| `options`        | Array of available options    | Array  | Required         | See below                      |
| `min_selections` | Minimum selections required   | Number | `0`              | `1`                            |
| `max_selections` | Maximum selections allowed    | Number | None             | `3`                            |
| `visibility`     | Display setting               | String | `always-visible` | `hide-when-empty`              |
| `section`        | Section this field belongs to | String | None             | Section UUID                   |

### Options Configuration

Each option in the `options` array:

| Property | Description                | Type   | Required | Example            |
| -------- | -------------------------- | ------ | -------- | ------------------ |
| `value`  | Internal value stored      | String | Yes      | `health_insurance` |
| `label`  | Display text shown to user | String | Yes      | "Health Insurance" |

## Examples

### Services Selection

Allow multiple service selections:

```json theme={null}
{
  "key": "services_required",
  "type": "multiple_choice",
  "name": "Services Required",
  "description": "Select all services you need",
  "min_selections": 1,
  "options": [
    { "value": "life_insurance", "label": "Life Insurance" },
    { "value": "health_insurance", "label": "Health Insurance" },
    { "value": "property_insurance", "label": "Property Insurance" },
    { "value": "liability_insurance", "label": "Liability Insurance" },
    { "value": "pension_planning", "label": "Pension Planning" }
  ]
}
```

### Document Types

Select required documents:

```json theme={null}
{
  "key": "required_documents",
  "type": "multiple_choice",
  "name": "Required Documents",
  "description": "Select all documents you need to submit",
  "options": [
    { "value": "id_card", "label": "ID Card or Passport" },
    { "value": "proof_of_address", "label": "Proof of Address" },
    { "value": "bank_statement", "label": "Bank Statement" },
    { "value": "tax_return", "label": "Tax Return" },
    { "value": "employment_contract", "label": "Employment Contract" }
  ]
}
```

### Coverage Areas

Select applicable coverage:

```json theme={null}
{
  "key": "coverage_areas",
  "type": "multiple_choice",
  "name": "Coverage Areas",
  "description": "Select all areas where coverage is needed",
  "max_selections": 3,
  "options": [
    { "value": "europe", "label": "Europe" },
    { "value": "north_america", "label": "North America" },
    { "value": "asia", "label": "Asia" },
    { "value": "africa", "label": "Africa" },
    { "value": "south_america", "label": "South America" },
    { "value": "oceania", "label": "Oceania" }
  ]
}
```

## Validation

Multiple Choice fields enforce selection validation:

### Selection Count

* `min_selections` - Minimum required selections
* `max_selections` - Maximum allowed selections
* User must select within range to proceed

### Option Validation

* User can only select from predefined options
* No free-form input
* Ensures data consistency

**Common configurations:**

| Configuration    | Use Case                      |
| ---------------- | ----------------------------- |
| `min: 1`         | "Select at least one"         |
| `min: 1, max: 3` | "Select 1-3 options"          |
| `min: 0`         | Optional selections (default) |
| `max: 5`         | Limit selections              |

## Stored Values

Multiple Choice fields store an array of selected values:

**Example stored data:**

```json theme={null}
{
  "services_required": [
    "life_insurance",
    "health_insurance",
    "pension_planning"
  ]
}
```

**Empty state:**

```json theme={null}
{
  "services_required": []
}
```

This format enables easy checking in automations and data processing.

## Multiple Choice in Automations

Multiple Choice fields enable conditional logic based on selections:

**Check if specific option selected:**

```json theme={null}
{
  "condition": {":in": "life_insurance", "{data.services_required}"}
}
```

**Check if any selection made:**

```json theme={null}
{
  "condition": {":gt": {":len": "{data.services_required}"}, "0"}
}
```

**Check if multiple selections:**

```json theme={null}
{
  "condition": {":gte": {":len": "{data.services_required}"}, "2"}
}
```

**Trigger based on selection:**

* Show additional steps for specific services
* Route to specialist based on selections
* Calculate pricing based on options selected
* Send targeted information based on interests

[Learn more about Automations →](/cases/automations)

## Best Practices

**Keep option lists focused:**

* 3-8 options is ideal
* More than 12 options becomes overwhelming
* Group related options logically
* Order by frequency of use or alphabetically

**Use clear labels:**

* Labels should be self-explanatory
* Avoid jargon or abbreviations
* Be consistent with terminology

**Consider min/max:**

* Use `min: 1` when at least one selection required
* Use `max` to prevent over-selection
* Most use cases don't need max limit

**Name the field as a question:**

* "Services Required" → clear what to select
* "Select Your Preferences" → action-oriented
* Avoid vague labels like "Options"

**Value vs Label:**

* Use short, technical values (`life_insurance`)
* Use friendly, readable labels ("Life Insurance")
* Values are used in code, labels shown to users

**Default selections:**

* Usually best to have no defaults
* Let users make explicit choices
* Pre-selecting can create unwanted selections

***

## Related Field Types

<CardGroup cols={2}>
  <Card title="Choices" icon="circle-dot" href="/cases/data_schema/choices">
    Use for single selection from options
  </Card>

  <Card title="Checkbox" icon="square-check" href="/cases/data_schema/checkbox">
    Use for single yes/no option
  </Card>

  <Card title="Text" icon="text" href="/cases/data_schema/text">
    Use for free-form input without predefined options
  </Card>

  <Card title="Data Schema Overview" icon="sitemap" href="/cases/data_schema">
    Back to Data Schema overview
  </Card>
</CardGroup>