> ## 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.

# Choices Field

> Single selection from predefined options

The Choices field allows users to select a single option from a predefined list. This field type displays as radio buttons or a dropdown menu, ensuring users choose exactly one option from the available choices.

Use Choices fields when you need to collect a single selection from a fixed set of possibilities — country, priority, status, category, or any scenario where only one option should be selected.

## When to Use

**Use Choices fields for:**

* Country or region selection
* Priority levels (low, medium, high)
* Categories or types
* Status indicators
* Gender or salutation
* Yes/No questions with additional options
* Industry or sector
* Payment methods
* Communication preferences
* Urgency levels

**Consider alternatives:**

* Use **Multiple Choice** for selecting multiple items
* Use **Checkbox** for simple yes/no only
* Use **Text** for free-form input

## Configuration Options

| Option        | Description                   | Type    | Default          | Example               |
| ------------- | ----------------------------- | ------- | ---------------- | --------------------- |
| `key`         | Unique identifier             | String  | Required         | `country`             |
| `name`        | Display label                 | String  | Required         | "Country"             |
| `description` | Help text for users           | String  | Optional         | "Select your country" |
| `options`     | Array of available options    | Array   | Required         | See below             |
| `required`    | Must select an option         | Boolean | `false`          | `true`                |
| `default`     | Default selected value        | String  | None             | `belgium`             |
| `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      | `belgium` |
| `label`  | Display text shown to user | String | Yes      | "Belgium" |

## Examples

### Country Selection

Select a single country:

```json theme={null}
{
  "key": "country",
  "type": "choices",
  "name": "Country",
  "description": "Select your country of residence",
  "required": true,
  "options": [
    { "value": "belgium", "label": "Belgium" },
    { "value": "france", "label": "France" },
    { "value": "germany", "label": "Germany" },
    { "value": "netherlands", "label": "Netherlands" },
    { "value": "luxembourg", "label": "Luxembourg" },
    { "value": "other", "label": "Other" }
  ]
}
```

### Priority Level

Set case priority:

```json theme={null}
{
  "key": "priority",
  "type": "choices",
  "name": "Priority",
  "description": "How urgent is this request?",
  "default": "medium",
  "options": [
    { "value": "low", "label": "Low - Routine" },
    { "value": "medium", "label": "Medium - Normal" },
    { "value": "high", "label": "High - Urgent" },
    { "value": "critical", "label": "Critical - Immediate" }
  ]
}
```

### Industry Sector

Select industry:

```json theme={null}
{
  "key": "industry",
  "type": "choices",
  "name": "Industry Sector",
  "description": "Primary business sector",
  "required": true,
  "options": [
    { "value": "finance", "label": "Financial Services" },
    { "value": "healthcare", "label": "Healthcare" },
    { "value": "technology", "label": "Technology" },
    { "value": "manufacturing", "label": "Manufacturing" },
    { "value": "retail", "label": "Retail" },
    { "value": "real_estate", "label": "Real Estate" },
    { "value": "other", "label": "Other" }
  ]
}
```

### Yes/No/Maybe

Three-option choice:

```json theme={null}
{
  "key": "renewal_intention",
  "type": "choices",
  "name": "Do you intend to renew?",
  "description": "Let us know your renewal plans",
  "options": [
    { "value": "yes", "label": "Yes, I will renew" },
    { "value": "no", "label": "No, I will not renew" },
    { "value": "undecided", "label": "Not sure yet" }
  ]
}
```

## Validation

Choices fields enforce single-selection validation:

### Required Validation

* If `required: true`, user must select an option
* Empty selection not allowed
* Useful for essential categorization

### Option Validation

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

## Stored Values

Choices fields store a single string value:

**Example stored data:**

```json theme={null}
{
  "country": "belgium"
}
```

**Empty state:**

```json theme={null}
{
  "country": null
}
```

The stored value is the `value` from the selected option, not the `label`.

## Choices in Automations

Choices fields enable powerful conditional workflows:

**Check for specific value:**

```json theme={null}
{
  "condition": {":eq": "{data.country}", "belgium"}
}
```

**Check if value in set:**

```json theme={null}
{
  "condition": {":in": "{data.priority}", ["high", "critical"]}
}
```

**Route based on selection:**

* Assign to country-specific team based on country
* Escalate high-priority cases automatically
* Show industry-specific steps based on industry
* Apply different pricing based on category

**Status transitions:**

* Move to "Urgent Queue" when priority is high
* Route to specialist when specific industry selected
* Apply different SLAs based on priority

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

## Best Practices

**Keep option lists manageable:**

* 3-12 options is ideal
* More than 20 options: consider search functionality or text input
* Group logically (alphabetically or by frequency)

**Use clear, distinct labels:**

* Each option should be clearly different
* Avoid similar or overlapping choices
* Use consistent terminology

**Always include "Other" when appropriate:**

* Provides escape hatch for unlisted options
* Prevents forcing users into wrong category
* Can trigger follow-up for details

**Value vs Label clarity:**

* Values: short, technical, consistent (e.g., `belgium`)
* Labels: friendly, readable (e.g., "Belgium")
* Values don't change, labels can be updated

**Order options logically:**

* Alphabetical for countries and names
* Most common first for frequency-based
* Logical progression for priority/urgency
* Group related options together

**Set defaults carefully:**

* Only set default if there's a clear common choice
* Don't default to first option (users may not notice)
* Leave blank when user should actively choose

**Required vs Optional:**

* Mark required when choice is essential
* Leave optional when "prefer not to say" is valid
* Consider if "no selection" is a valid state

***

## Related Field Types

<CardGroup cols={2}>
  <Card title="Multiple Choice" icon="list-check" href="/cases/data_schema/multiple_choice">
    Use for selecting multiple options
  </Card>

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

  <Card title="Text" icon="text" href="/cases/data_schema/text">
    Use when predefined options aren't suitable
  </Card>

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