> For the complete documentation index, see [llms.txt](https://kb.craftformswp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kb.craftformswp.com/documentation/form-building/create-form/blocks/phone-field.md).

# Phone Field

The Phone field asks for a phone number with a country flag and dial code in front of it. Visitors pick their country from a list, or just type the number with its code (+44…) and the flag changes by itself. CraftForms checks that the number has the right length and format for that country, so you get numbers you can actually call or message, and it saves them all in one international format.

![The Phone field with its country list open](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2FddvupjJbOZx3I6jG8YBi%2Fphone-field--country-list.jpg?alt=media)

### What you need

* **CraftForms (free)**, version 2.2 or later. The Phone field is in the free version.
* Nothing else. The flags come with the plugin, so the field loads nothing from other websites.

### Add a Phone field

1. Open your form in the editor (**CraftForms → Forms → Edit**).
2. Click the **+** (block inserter), type **phone**, and choose **Phone**.
3. With the field selected, give it a **Label** in the block settings, like "Mobile phone".
4. Optional: set the **Default country**, the **Countries at the top of the list** and **Allow only these countries** in the **Phone** panel (see below).
5. Turn on **Required** (in the **Validation** panel) if the form must not be sent without a number.
6. Save the form.

The Phone field is a Text Input Field with the country picker turned on. It keeps everything a Text Input Field has: conditions, Field Links, columns, the help popup.

**Already have a phone input?** Select the Text Input Field, set **Input Type** to **Phone (tel)**, and turn on **Country picker** in the **Phone** panel. Phone inputs made before 2.2 stay plain text inputs until you do this.

### Settings

![The Phone panel in the block settings](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2FKLGH0l3fHiqjJDQmqyyJ%2Fphone-field--block-settings.jpg?alt=media)

The **Phone** panel shows when the **Input Type** is **Phone (tel)**.

| Setting                              | What it does                                                                                                                                                                                                                                           |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Country picker**                   | On: the flag and dial code show before the number, the number is checked for its country and saved in international form. Off: a plain phone input that accepts any text.                                                                              |
| **Default country**                  | The country the field starts with. **Automatic (visitor's browser language)** (the default) takes it from the visitor's browser language, for example German (Germany) → Germany. Nothing is looked up online. Pick a country to always start with it. |
| **Countries at the top of the list** | Countries shown first in the list, above a line. Handy when most of your visitors come from a few countries.                                                                                                                                           |
| **Allow only these countries**       | Only these countries are in the list and accepted. Leave it empty to allow every country.                                                                                                                                                              |

With **Automatic**, the field uses the visitor's browser language first, then your site's language. If neither names a country, it starts with the first allowed country, then the first country at the top of the list, then the United States.

In the editor, the field shows the default country's flag (a globe for **Automatic**). The list itself works on the page.

### What your visitor sees

* A flag button inside the field. When they click into an empty field, the dial code of the country is already there (`+44` ), so they only type the rest.
* **Typing a code picks the country.** Type or paste `+33 6 12 34 56 78` and the flag turns French. Numbers that share a code, like +1 for the USA and Canada, get the right country from the area code.
* **Typing a local number works too.** `07700 900123` with the UK selected becomes `+44 7700900123` when they leave the field. A 0 typed after the code (`+44 07700…`) is dropped when the number needs it gone, and kept in countries like Italy where it belongs to the number.
* **Picking a country from the list** keeps the digits already typed and changes the code in front.
* **The country list** has a search box: type a country name (in your site's language or the visitor's own), a country code like `DE`, or a dial code like `+49`. The arrow keys, Enter and Esc work, and Enter never sends the form.
* If they leave the field with only the dial code in it, the field is emptied.

### Checking the number

A number is accepted when it is complete and possible for its country: the right number of digits and the right format, using the same country data as Google's libphonenumber (245 countries and territories). It doesn't check that the number is in use.

The number is checked in the browser as the visitor types, and again on your server when the form is sent, with the same data. **Allow only these countries** is checked on the server too.

![The error message for an incomplete phone number](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2FozpBb9AuqMCqlHK6aP36%2Fphone-field--invalid-number.jpg?alt=media)

To change the messages, open **Validation Messages** in the block settings:

| Message          | When it shows                                          |
| ---------------- | ------------------------------------------------------ |
| **Required**     | The field is required and empty.                       |
| **Phone Number** | The number is incomplete or not valid for its country. |

Leave them empty to use the site-wide texts. The built-in phone message is *Please enter a valid phone number for {{fieldLabel}}.* Change or translate it for all forms in **CraftForms → Settings → Field Message Translations**, row **Invalid phone number** (see [Field Message Translations](/documentation/form-building/general-settings/field-message-translations.md)).

### How the number is saved

The field shows the number as `+44 7700900123`. It is saved without spaces, in the international format known as E.164: `+447700900123`. That's the value you see in **CraftForms → Submissions** and that goes into emails, PDFs and webhooks. Every number has its country code, so it works with tools like WhatsApp, SMS services and CRMs.

Conditions and formulas see the number as it is in the field, like any text field.

### Styles

The field works with every form style: **Default**, **Modern**, **Builderius CSS** and **Unstyled**. The style draws the input as usual; the Phone field only adds the flag button and the list, and takes its colours from the style.

### Good to know

* The field needs JavaScript for the flag and the list. It doesn't use jQuery or any other library.
* Country names in the list come from the visitor's browser, in your site's language.
* The field only checks the format. To be sure a number belongs to the visitor, you'd need a confirmation code by SMS, which CraftForms doesn't send.
* A plain **Phone (tel)** input with **Country picker** off accepts any text and is saved as typed.