Telephone input
Create telephone inputs in your forms.

Use the telInput()
function to create telephone inputs in your forms. It uses the HTML <input type="tel">
element which provides built-in telephone format validation.
Basic usage
import { Composer } from "formsmd";
const composer = new Composer({
id: "my-form"
});
composer.telInput("phone", {
question: "What is your phone number?"
});
Generates the following Markdown-like syntax:
#! id = my-form
phone = TelInput(
| question = What is your phone number?
)
Required
Add the required
parameter to make the field mandatory:
composer.telInput("phone", {
question: "What is your phone number?",
required: true
});
Generates the following Markdown-like syntax:
phone* = TelInput(
| question = What is your phone number?
)
Function overview
The following is the overview of the function:
telInput(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 telephone 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.
Telephone input specific parameters
placeholder
string
Sets the placeholder
attribute of the input.
maxlength
number
If set, this becomes the maximum number of allowed characters in the input.
pattern
string
If set, the input value must match the given pattern.
value
string
If set, this becomes the default value of the input.
country
string
The default country code (e.g., "US"
, "CA"
, "GB"
, etc. Defaults to "US"
if not specified. ISO alpha-2 format.
availableCountries
string[]
Array of available country codes (e.g., ["US", "CA", "GB"]
).
Examples
Telephone input with custom placeholder
composer.telInput("contactPhone", {
question: "What's your phone number?",
description: "We'll use this number to contact you if needed",
placeholder: "(555) 123-4567",
required: true
});
Generates the following Markdown-like syntax:
contactPhone* = TelInput(
| question = What's your phone number?
| description = We'll use this number to contact you if needed
| placeholder = (555) 123-4567
)
Telephone input with specific country and available countries
composer.telInput("phoneNumber", {
question: "Phone number",
description: "Please provide a UK phone number",
country: "GB",
availableCountries: ["GB", "IE"],
required: true
});
Generates the following Markdown-like syntax:
phoneNumber* = TelInput(
| question = Phone number
| description = Please provide a UK phone number
| country = GB
| availableCountries = GB, IE
)
Styled telephone input with custom attributes
Add CSS classes and other HTML attributes using the classNames
and attrs
parameters. Please note, these class names and attributes are added to the <div>
or <fieldset>
container that contains the actual input field(s).
composer.telInput("phoneNumber", {
question: "Phone number",
classNames: ["col-6", "xs:col-6"],
attrs: [
{ name: "style", value: "font-size: 18px;" }
]
});
Generates the following Markdown-like syntax:
[.col-6 .xs:col-6 style="font-size: 18px;"]
phoneNumber = TelInput(
| question = Phone number
)
Please see the available CSS utility classes.
Conditional display
Conditionally show or hide a telephone input field 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 mobile phone input will only show up if the user indicates they want to receive SMS notifications.
composer.choiceInput("wantSMS", {
question: "Would you like to receive SMS notifications?",
required: true,
choices: ["Yes", "No"]
})
composer.telInput("mobilePhone", {
question: "Mobile phone number",
displayCondition: {
dependencies: ["wantSMS"],
condition: "wantSMS == 'Yes'"
}
});
Generates the following Markdown-like syntax:
wantSMS* = ChoiceInput(
| question = Would you like to receive SMS notifications?
| choices = Yes, No
)
::: [{$ wantSMS $}]
{% if wantSMS == "Yes" %}
mobilePhone = TelInput(
| question = Mobile phone number
)
{% endif %}
:::
Notes
The selected country code is sent separately from the actual phone number during form submission. For example, if we had an input with the name
contactNumber
, the actual number would be sent under thecontactNumber
key, while the selected country code would be sent under thecontactNumberCountryCode
.
Last updated
Was this helpful?