Skip to main content

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.

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

OptionDescriptionTypeDefaultExample
keyUnique identifierStringRequiredcountry
nameDisplay labelStringRequired”Country”
descriptionHelp text for usersStringOptional”Select your country”
optionsArray of available optionsArrayRequiredSee below
requiredMust select an optionBooleanfalsetrue
defaultDefault selected valueStringNonebelgium
visibilityDisplay settingStringalways-visiblehide-when-empty
sectionSection this field belongs toStringNoneSection UUID

​
Options Configuration

Each option in the options array:
PropertyDescriptionTypeRequiredExample
valueInternal value storedStringYesbelgium
labelDisplay text shown to userStringYes”Belgium”

​
Examples

​
Country Selection

Select a single country: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "country": "belgium"
}
Empty state: 
{
  "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: 
{
  "condition": {":eq": "{data.country}", "belgium"}
}
Check if value in set: 
{
  "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 →

​
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

Multiple Choice

Use for selecting multiple options

Checkbox

Use for simple yes/no only

Text

Use when predefined options aren’t suitable

Data Schema Overview

Back to Data Schema overview