choiceInput

Create radio button or checkbox inputs for single or multiple selections

Overview

The choiceInput method creates radio button inputs for single selections or checkbox inputs for multiple selections. It provides a clean interface for users to choose from a predefined set of options.

Method Signature

choiceInput(
  name: string,
  params: FormFieldSharedParamsType & ChoiceInputParamsType
): string

Parameters

name · string · required

The unique identifier for this input field. Used to reference the selected value(s) in form submissions.

Required Parameters

question · string · required

The main question or label displayed to the user.

choices · (string | ChoiceOptionType)[] · required

Array of choices as strings or objects with label and value properties.

// Simple string array
choices: ["Option A", "Option B", "Option C"]

// With custom values
choices: [
  { label: "Option A", value: "a" },
  { label: "Option B", value: "b" }
]

Input-Specific Parameters

multiple · boolean

When set to true, allows multiple selections using checkboxes instead of radio buttons.

multiple: true

horizontal · boolean

When set to true, displays choices horizontally instead of vertically.

horizontal: true

hideFormText · boolean

When set to true, hides the question and description, showing only the choices.

hideFormText: true

checked · string[]

Array of pre-checked choice values (must match the value property).

checked: ["option1", "option2"]

Shared Parameters

All standard form field parameters are supported. See textInput for the complete list including required, description, fieldSize, disabled, and more.

Examples

Single Choice (Radio)

Basic

composer.choiceInput("plan", {
  question: "Select your subscription plan",
  choices: ["Free", "Pro", "Enterprise"],
  required: true
});

Multiple Choice (Checkboxes)

Basic

composer.choiceInput("interests", {
  question: "What topics interest you?",
  choices: ["Technology", "Design", "Marketing", "Sales"],
  multiple: true
});

Advanced Usage

Conditional Display

composer.choiceInput("planFeatures", {
  question: "Which additional features do you need?",
  choices: [
    { label: "Advanced Analytics", value: "analytics" },
    { label: "Priority Support", value: "support" },
    { label: "Custom Integrations", value: "integrations" }
  ],
  multiple: true,
  displayCondition: {
    dependencies: ["plan"],
    condition: "plan === 'enterprise'"
  }
});

Choice Types

Single Selection (Radio Buttons)

Default behavior - Radio buttons allow users to select only one option from the list.

When to use:

• Mutually exclusive options (only one can be true)
• Subscription tiers or plans
• Yes/No questions
• Single preference selection

composer.choiceInput("size", {
  question: "Select your size",
  choices: ["Small", "Medium", "Large", "X-Large"]
});

Multiple Selection (Checkboxes)

Set multiple: true to allow users to select multiple options.

When to use:

• Non-exclusive options (multiple can be true)
• Feature selections
• Interest categories
• Permission settings
• Multi-select preferences

composer.choiceInput("toppings", {
  question: "Select your pizza toppings",
  choices: ["Pepperoni", "Mushrooms", "Olives", "Peppers"],
  multiple: true,
  description: "Choose as many as you like"
});

Layout Options

Vertical (Default)

Choices are stacked vertically, which is ideal for:

• Longer choice labels
• Many options (5+)
• Small screen sizes

composer.choiceInput("country", {
  question: "Select your country",
  choices: ["United States", "Canada", "United Kingdom", "Australia"]
});

Horizontal

Choices are displayed in a row using horizontal: true. Best for:

• Short labels
• Few options (2-4)
• Rating scales
• Yes/No questions

composer.choiceInput("rating", {
  question: "Rate your experience",
  choices: ["Poor", "Fair", "Good", "Excellent"],
  horizontal: true
});

Use Cases

Product Selection

Let users choose product variants, sizes, or options.

Survey Questions

Create survey forms with single or multiple choice questions.

Preferences

Collect user preferences and settings.

Agreement Forms

Get consent or agreement through yes/no choices.

Best Practices

Choice ordering

Order choices logically:

• Alphabetical for long lists
• Most common to least common
• Smallest to largest (sizes, numbers)
• Chronological (dates, time periods)

Choice labels

Keep labels clear and concise:

• Use parallel structure
• Be specific and unambiguous
• Avoid jargon unless necessary
• Keep length consistent when possible

When to use vs. select box

Use choiceInput when:

• 7 or fewer options
• Users need to see all options at once
• Visual comparison is important

Use selectBox when:

• 8 or more options
• Saving space is important
• Options are well-known (like countries)

Multiple selections

When using multiple: true:

• Indicate in the description that multiple selections are allowed
• Consider pre-selecting common or recommended options
• Don’t require selection if users may want none

description: "Choose all that apply"

Return Value

Returns a string containing the Forms.md markup for the choice input field.

Single selection returns: The value of the selected choice (string)

Multiple selection returns: Array of selected choice values (string[])

Related Methods

selectBox

Dropdown selection for longer lists

pictureChoice

Visual choice selection with images

ratingInput

Star or heart rating scales