Choice input
Create choice inputs in your forms.

Use the choiceInput()
function to create choice inputs in your forms. It allows users to select one or more options from a list of choices.
Basic usage
import { Composer } from "formsmd";
const composer = new Composer({
id: "my-form"
});
composer.choiceInput("interest", {
question: "What is your interest?",
choices: ["Programming", "Design", "Marketing"]
});
Generates the following Markdown-like syntax:
#! id = my-form
interest = ChoiceInput(
| question = What is your interest?
| choices = Programming, Design, Marketing
)
Required
Add the required
parameter to make the field mandatory:
composer.choiceInput("interest", {
question: "What is your interest?",
choices: ["Programming", "Design", "Marketing"],
required: true
});
Generates the following Markdown-like syntax:
interest* = ChoiceInput(
| question = What is your interest?
| choices = Programming, Design, Marketing
| required
)
Function overview
The following is the overview of the function:
choiceInput(name: string, params: object)
Arguments
name
string
A unique name for your form field that you'll use to identify the user's response.*
params
object
An object containing all the configuration parameters for your choice input field (see the parameters section below for the full list of options).
*Avoid values for the name
argument which may be the names of HTML attributes, such as "name"
, "role"
, "id"
, etc. This is because by default, the form's template string is first sanitized using DOMPurify, and these values may be removed to prevent DOM clobbering.
Parameters
Shared parameters
These parameters are common to all form fields:
question
(required)
string
The main question or label of the form field.
required
true
(boolean
)
When set, the field becomes required.
description
string
Any extra information that the user may need to fill out the form. Appears right below the question.
fieldSize
"sm"
When set to "sm"
, the font sizes of the question, description, and answer are made smaller.
labelStyle
"classic"
When set to "classic"
, the question and description of the form field are made smaller.
subfield
true
(boolean
)
When set, the question and description of the form field are made smaller. Functionally the same as setting labelStyle
to "classic"
.
disabled
true
(boolean
)
When set, the input is disabled.
autofocus
true
(boolean
)
When set, the input will be automatically focused when the parent slide becomes active, or immediately after page load.
id
string
The id
attribute of the form field container.
attrs
Array<{ name: string, value: string }>
Other HTML attributes of the form field. Each attribute has a name
and value
property.
displayCondition
{ dependencies: string[], condition: string }
Controls when the field is shown. The dependencies
lists the fields to watch, and condition
is the expression that must be true to show the field. The condition
must be a valid Nunjucks expression. See example.
Choice input specific parameters
choices
(required)
Array<string | { label: string, value?: string }>
Array of choices that can be either strings (e.g., ["Choice 1", "Choice 2"]
) or objects with a label
for display text and an optional value
(e.g., [{ label: "Choice 1", value: "c1" }]
). When using objects, if value
is not provided, label
is used as the value.
multiple
true
(boolean
)
Allow multiple selections.
horizontal
true
(boolean
)
Display choices horizontally.
hideFormText
true
(boolean
)
For multiple selections, when set, the form text "Choose as many as you like" is hidden.
checked
string[]
Array of pre-checked choice values.
Examples
Choice input with value-label pairs
Value-label pairs allow different values to be stored than what's shown to users. The label
appears for users to select, while the value
is stored in the form data. This pattern is particularly useful for storing concise identifiers in a database while displaying more descriptive text in the interface.
Please note, for checked
to work with value-label pairs, it must contain the value
, not the label
.
composer.choiceInput("experience", {
question: "Select levels you've completed",
choices: [
{ label: "Beginner (0-1 years)", value: "beginner" },
{ label: "Intermediate (2-4 years)", value: "intermediate" },
{ label: "Advanced (5+ years)", value: "advanced" }
],
checked: ["beginner", "intermediate"],
multiple: true,
required: true
});
Generates the following Markdown-like syntax:
experience* = ChoiceInput(
| question = Select levels you've completed
| choices = "beginner" Beginner (0-1 years), "intermediate" Intermediate (2-4 years), "advanced" Advanced (5+ years)
| checked = begineer, intermediate
| multiple
)
Horizontal choice input
Create a horizontally aligned choice input using the horizontal
parameter:
composer.choiceInput("subscription", {
question: "Choose your subscription plan",
choices: ["Basic", "Pro", "Enterprise"],
horizontal: true
});
Generates the following Markdown-like syntax:
subscription = ChoiceInput(
| question = Choose your subscription plan
| choices = Basic, Pro, Enterprise
| horizontal
)
Styled choice input with custom attributes
Add CSS classes and other HTML attributes using the classNames
and attrs
parameters:
composer.choiceInput("preferences", {
question: "Select your preferences",
choices: ["Email notifications", "SMS alerts", "Push notifications"],
multiple: true,
classNames: ["col-6", "xs:col-6"],
attrs: [
{ name: "style", value: "margin-top: 1rem;" }
]
});
Generates the following Markdown-like syntax:
[.col-6 .xs:col-6 style="margin-top: 1rem;"]
preferences = ChoiceInput(
| question = Select your preferences
| choices = Email notifications, SMS alerts, Push notifications
| multiple
)
Please see the available CSS utility classes.
Conditional display
Conditionally show or hide a choice input using the displayCondition
parameter. It works as follows:
dependencies
lists the fields to watch.condition
is the expression that must be true to show the field. This must be a valid Nunjucks expression.
For instance, in the example below, the programming languages choice will only show up if the user indicates they are a developer.
composer.choiceInput("position", {
question: "What is your position?",
choices: ["Developer", "Designer", "Manager"],
required: true
});
composer.choiceInput("languages", {
question: "Which programming languages do you use?",
choices: ["JavaScript", "Python", "Java", "C++"],
multiple: true,
displayCondition: {
dependencies: ["position"],
condition: "position == 'Developer'"
}
});
Generates the following Markdown-like syntax:
position* = ChoiceInput(
| question = What is your position?
| choices = Developer, Designer, Manager
)
::: [{$ position $}]
{% if position == "Developer" %}
languages = ChoiceInput(
| question = Which programming languages do you use?
| choices = JavaScript, Python, Java, C++
| multiple
)
{% endif %}
:::
Last updated
Was this helpful?