# Telephone input

Telephone input

Use the `telInput()` function to create telephone inputs in your forms. It uses the HTML `` element which provides built-in telephone format validation. *** ## Basic usage ```javascript 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: ```javascript 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: ```typescript telInput(name: string, params: object) ``` ### Arguments | Name | Type | Description | | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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](#parameters) below for the full list of options). | {% hint style="danger" %} \*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](https://github.com/cure53/DOMPurify), and these values may be removed to prevent DOM clobbering. {% endhint %} *** ## Parameters ### Shared parameters These parameters are common to all form fields: | Name | Type | Description | | --------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | | `classNames` | `string[]` | The CSS class names of the form field. [See the available CSS utility classes](https://docs.forms.md/content/css-utility-classes). | | `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](https://mozilla.github.io/nunjucks/) expression. [See example](#conditional-display). | ### Telephone input specific parameters | Name | Type | Description | | -------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | | `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 ```javascript 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 ```javascript 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 `
` or `
` container that contains the actual input field(s). ```javascript 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](https://docs.forms.md/content/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](https://mozilla.github.io/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. ```javascript 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 the `contactNumber` key, while the selected country code would be sent under the `contactNumberCountryCode`. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.forms.md/input-types/tel-input.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.