---
title: 'Input Tel: Use Cases'
parts:
- Input Tel
- Use Cases
eleventyNavigation:
key: 'Input Tel: Use Cases'
order: 20
parent: Input Tel
title: Use Cases
---
# Input Tel: Use Cases
```js script
import { html } from '@mdjs/mdjs-preview';
import { ref, createRef } from 'lit/directives/ref.js';
import { Unparseable } from '@lion/ui/form-core.js';
import { localize } from '@lion/ui/localize.js';
import { loadDefaultFeedbackMessages } from '@lion/ui/validate-messages.js';
import { PhoneUtilManager } from '@lion/ui/input-tel.js';
import '@lion/ui/define/lion-input-tel.js';
import './src/h-region-code-table.js';
import '../../../docs/fundamentals/systems/form/assets/h-output.js';
// TODO: make each example load/use the dependencies by default
// loadDefaultFeedbackMessages();
```
## Regions: some context
Say we have the following telephone number from Madrid, Spain: `+34919930432`.
It contains a [country code](https://en.wikipedia.org/wiki/Country_code) (34), an [area code](https://en.wikipedia.org/wiki/Telephone_numbering_plan#Area_code) (91) and a [dial code](https://en.wikipedia.org/wiki/Mobile_dial_code) (+34 91).
Input Tel interprets phone numbers based on their [region code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2): a two character long region representation('ES' in the telephone number above).
The table below lists all possible regions worldwide. When [allowed regions](#allowed-regions) are not configured,
all of them will be supported as values of Input Tel.
```js story
export const regionCodesTable = () => {
loadDefaultFeedbackMessages();
return html``;
};
```
### Active region
The active region (accessible via readonly accessor `.activeRegion`) determines how validation and formatting
should be applied. It is dependent on the following factors:
- [allowed regions](#allowed-regions): a list that determines what is allowed to become .activeRegion. If
[.allowedRegions has only one entry](#restrict-to-one-region), .activeRegion will always be this value.
- the modelValue or viewValue: once it contains sufficient info to derive its region code (and
the derived code is inside [allowed regions](#allowed-regions) if configured)
- active locale (and the derived locale is inside [allowed regions](#allowed-regions) if configured)
What follows from the list above is that .activeRegion can change dynamically, after a value
change in the text box by the user (or when locales or allowed regions would be changed by the
Application Developer).
### How active region is computed
The following heuristic will be applied:
1. check for **allowed regions**: if one region defined in .allowedRegions, use it.
2. check for **user input**: try to derive active region from user input
3. check for **locale**: try to get the region from locale (`html[lang]` attribute)
```js preview-story
export const heuristic = () => {
loadDefaultFeedbackMessages();
const initialAllowedRegions = ['CN', 'ES'];
const [inputTelRef, outputRef, selectRef] = [createRef(), createRef(), createRef()];
const setDerivedActiveRegionScenario = (
scenarioToSet,
inputTel = inputTelRef.value,
output = outputRef.value,
) => {
if (scenarioToSet === 'only-allowed-region') {
// activeRegion will be the top allowed region, which is 'NL'
inputTel.modelValue = undefined;
inputTel.allowedRegions = ['NL']; // activeRegion will always be the only option
output.innerText = '.activeRegion (NL) is only allowed region';
} else if (scenarioToSet === 'user-input') {
// activeRegion will be based on phone number => 'BE'
inputTel.allowedRegions = ['NL', 'BE', 'DE'];
inputTel.modelValue = '+3261234567'; // BE number
output.innerText = '.activeRegion (BE) is derived (since within allowedRegions)';
} else if (scenarioToSet === 'locale') {
localize.locale = 'en-GB';
// activeRegion will be `html[lang]`
inputTel.modelValue = undefined;
inputTel.allowedRegions = undefined;
output.innerText = `.activeRegion (${inputTel._langIso}) set to locale when inside allowed or all regions`;
} else {
output.innerText = '';
}
};
return html`
`;
};
```
## Allowed regions
`.allowedRegions` is an array of one or more region codes.
Once it is configured, validation and formatting will be restricted to those
values that are present in this list.
> Note that for [InputTelDropdown](../input-tel-dropdown/index.md), only allowed regions will
> be shown in the dropdown list.
```js preview-story
export const allowedRegions = () => {
loadDefaultFeedbackMessages();
return html`
`;
};
```
### Restrict to one region
When one allowed region is configured, validation and formatting will be restricted to just that
region (that means that changes of the region via viewValue won't have effect).
```js preview-story
export const oneAllowedRegion = () => {
loadDefaultFeedbackMessages();
return html`
`;
};
```
## Format
### Format strategy
Determines what the formatter output should look like.
Formatting strategies as provided by awesome-phonenumber / google-libphonenumber.
Possible values:
| strategy | output |
| :------------ | ---------------------: |
| e164 | `+46707123456` |
| international | `+46 70 712 34 56` |
| national | `070-712 34 56` |
| significant | `707123456` |
| rfc3966 | `tel:+46-70-712-34-56` |
Also see:
- [awesome-phonenumber documentation](https://www.npmjs.com/package/awesome-phonenumber)
```js preview-story
export const formatStrategy = () => {
loadDefaultFeedbackMessages();
const inputTel = createRef();
return html`
`;
};
```
### Format country code style
You can also style the country code with parentheses.
```js preview-story
export const formatCountryCodeStyle = () => {
loadDefaultFeedbackMessages();
const inputTel = createRef();
return html`
`;
};
```
### Live format
Type '6' in the example below to see how the phone number is formatted during typing.
See [awesome-phonenumber documentation](https://www.npmjs.com/package/awesome-phonenumber)
```js preview-story
export const liveFormat = () => {
loadDefaultFeedbackMessages();
return html`
`;
};
```
## Active phone number type
The readonly acessor `.activePhoneNumberType` outputs the current phone number type, based on
the textbox value.
Possible types: `fixed-line`, `fixed-line-or-mobile`, `mobile`, `pager`, `personal-number`, `premium-rate`, `shared-cost`, `toll-free`, `uan`, `voip`, `unknown`
Also see:
- [awesome-phonenumber documentation](https://www.npmjs.com/package/awesome-phonenumber)
```js preview-story
export const activePhoneNumberType = () => {
loadDefaultFeedbackMessages();
return html`
`;
};
```