telInput

Create telephone input fields with international country code support

Overview

The telInput method creates a telephone input field with automatic country code selection and formatting. It supports international phone numbers with country-specific placeholders and validation.

Method Signature

telInput(
  name: string,
  params: FormFieldSharedParamsType & TelInputParamsType
): string

Parameters

name · string · required

The unique identifier for this input field. Used to reference the phone number in form submissions.

Required Parameters

question · string · required

The main question or label displayed to the user.

Input-Specific Parameters

placeholder · string

Sets custom placeholder text. If not provided, a country-specific placeholder is automatically generated.

placeholder: "[phone]"

country · CountryCodeType

Default country code (2-letter ISO code). Defaults to "US" if not specified.

country: "GB"  // United Kingdom

See Country Codes for the full list of supported countries.

availableCountries · CountryCodeType[]

Array of country codes to allow. If provided, only these countries will be available in the country selector.

availableCountries: ["US", "CA", "GB", "AU"]

maxlength · number

Maximum number of allowed characters in the phone number input.

maxlength: 15

pattern · string

Custom regex pattern for phone number validation.

pattern: "^\\d{10}$"  // Exactly 10 digits

value · string

Default phone number value.

value: "555-123-4567"

Shared Parameters

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

Examples

Basic Phone Input

const composer = new Composer({ title: "Contact Form" });

composer.telInput("phone", {
  question: "What is your phone number?",
  required: true,
  country: "US"
});

Features

Country Selector

The telephone input automatically includes a country selector showing:

• Country flag
• Country calling code (e.g., +1, +44)
• Country name

composer.telInput("phone", {
  question: "Phone number",
  country: "US",  // Default to United States
  availableCountries: ["US", "CA", "MX"]  // North America
});

Users can click the country selector to choose a different country from the available options.

Smart Placeholders

Placeholders automatically update based on the selected country:

• US: [phone]
• GB: 07400 123456
• FR: 06 12 34 56 78
• DE: 0151 23456789

composer.telInput("phone", {
  question: "Phone number",
  country: "GB"  // Shows UK format placeholder
});

You can override with a custom placeholder:

placeholder: "Enter your number"

Calling Codes

The calling code is automatically displayed and updated:

// Shows: +1 (US/CA)
country: "US"

// Shows: +44 (GB)
country: "GB"

// Shows: +33 (FR)
country: "FR"

// Shows: +86 (CN)
country: "CN"

The calling code is prefixed to the submitted value.

Country Codes

Common Countries

Most frequently used country codes:

Code	Country	Calling Code
US	United States	+1
CA	Canada	+1
GB	United Kingdom	+44
AU	Australia	+61
DE	Germany	+49
FR	France	+33
IT	Italy	+39
ES	Spain	+34
NL	Netherlands	+31
CN	China	+86
JP	Japan	+81
IN	India	+91

All Supported Countries

The telInput method supports over 200 countries and territories. Some examples:

• North America: US, CA, MX
• Europe: GB, DE, FR, IT, ES, NL, SE, NO, DK, FI
• Asia: CN, JP, IN, KR, SG, TH, VN
• Oceania: AU, NZ
• South America: BR, AR, CL, CO
• Africa: ZA, EG, NG, KE

For the complete list, see the TypeScript definitions in the source code.

Regional Groups

Common regional groupings:

// North America
availableCountries: ["US", "CA", "MX"]

// European Union (sample)
availableCountries: ["DE", "FR", "IT", "ES", "NL", "BE"]

// English-speaking
availableCountries: ["US", "GB", "CA", "AU", "NZ", "IE"]

// Nordic countries
availableCountries: ["SE", "NO", "DK", "FI", "IS"]

Use Cases

Contact Forms

Collect phone numbers from customers for follow-up.

User Registration

Get phone numbers for account verification via SMS.

Delivery Information

Collect phone numbers for delivery coordination.

International Support

Support customers from multiple countries.

Best Practices

Set appropriate default country

Choose the most relevant default country for your audience:

// For US-based business
country: "US"

// For UK-based business
country: "GB"

// For international business (detect from IP or browser)
country: getUserCountry()  // Implement based on your needs

Limit available countries

If you only operate in specific regions, limit the country list:

composer.telInput("phone", {
  question: "Phone number",
  country: "US",
  availableCountries: ["US", "CA"],
  description: "We currently only serve US and Canada"
});

Clear formatting expectations

Use descriptions to clarify expectations:

description: "Include country code if outside the US"
description: "We'll use this number for delivery updates"
description: "SMS verification will be sent to this number"

Consider validation needs

Add pattern validation for strict requirements:

// US only: exactly 10 digits
pattern: "^[0-9]{10}$",
availableCountries: ["US"],
description: "10-digit US phone number"

// International: allow varying lengths
// No pattern needed, default validation handles it

Validation

Phone number validation varies by country. The input uses the HTML5 tel type with optional pattern validation.

// Basic validation (any phone format)
composer.telInput("phone", {
  question: "Phone number",
  required: true
});

// Strict US validation
composer.telInput("usPhone", {
  question: "US phone number",
  required: true,
  country: "US",
  availableCountries: ["US"],
  pattern: "^[0-9]{10}$",
  description: "10 digits, no spaces or dashes"
});

// International with length limit
composer.telInput("intlPhone", {
  question: "International phone",
  required: true,
  maxlength: 15,
  description: "Maximum 15 digits"
});

Return Value

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

Submitted value format: The calling code and phone number, e.g., "[phone]"

Related Methods

textInput

General text input for non-phone text

emailInput

Email input with validation

numberInput

Numeric input for phone extensions