Live Demo
<ba-input-phone-number label="Phone number" name="phoneNumber" hint-text="Please enter your phone number" required></ba-input-phone-number>
Guidelines
This component should only be used for entering phone numbers. For text use ba-input-text or ba-input-textarea and for numbers use ba-input-number
As ba-input-phone-number contains multiple inputs you cannot get both values by using the value property like you can with the other form inputs. Doing this will only get the phone number value, but not the country code. To get both values you must listen for the baOnInput event, as this emits out both the country code and the entered value.
When using BAgel with a bundler such as webpack the flag assets may not get copied over. You can fix this by setting the asset path for BAgel. Info for this can be found at the bottom of the Getting started page.
Accessibility
Always use the label attribute to give a meaningful label to the field.
Further reading:
Disabled form elements are not supported in BAgel because they create accessibility challenges, such as preventing keyboard navigation, confusing screen reader users, and reducing visual clarity for those with impairments
Further reading:
Placeholders on inputs are not supported in BAgel because they create accessibility challenges, such as failing to provide persistent labels for screen readers, reducing color contrast for users with visual impairments, and causing confusion for those with cognitive difficulties.
If you would like to add a infomations to help the user fill the input, you can use the hint-text attribute.
Further reading:
The main input uses the tel-national autocomplete value. This is allows the autocomplete to fill in the field without the country code extension.
More info here HTML attribute: autocomplete
Make sure the component has enough room for both the input and the country code text to expand. For example if the user has increased the font size of the page.
Code
Properties & Attributes
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
countryCode |
country-code |
The selected country code | string | undefined |
'gb' |
hintText |
hint-text |
Hint text to show above the input | string | undefined |
undefined |
invalid |
invalid |
Whether the input is invalid | boolean | undefined |
false |
label(required) |
label |
A label for the input | string |
undefined |
maxLength |
max-length |
Max amount of characters allowed in validation | string | undefined |
undefined |
minLength |
min-length |
Min amount of characters allowed in validation | string | undefined |
undefined |
name |
name |
The name of the input | string | undefined |
undefined |
priorityCodes |
priority-codes |
List of priority codes for the country selector | string | undefined |
'gb,us' |
required |
required |
Whether the input is required | boolean | undefined |
false |
value |
value |
The value of the input | string | undefined |
'' |
Events
| Event | Description | Type |
|---|---|---|
baBlur |
Emitted when the input loses focus. | CustomEvent<void> |
baFocus |
Emitted when the input has focus. | CustomEvent<void> |
baOnInput |
Emitted when a keyboard input ocurred. | CustomEvent<KeyboardEvent> |
baSubmit |
Emitted when the user submits the form from within the component | CustomEvent<void> |
Methods
isValid() => Promise<boolean>
An exposed method for triggering the inputs required validation
reset() => Promise<void>
Resets the input back to its initial value
Returns
Type: Promise<void>
`getData() => Promise`
Returns the currently selected country code, dialing code and input value
Returns
Type: Promise<InputChangeEventDetail>
Slots
| Slot | Description | Permitted elements |
|---|---|---|
"error" |
Element will be rendered in the error slot | <p> |
"error-required" |
Element will be rendered in the error-required slot | <p> |
"error-min-length" |
Element will be rendered in the error-min-length slot | <p> |
"error-max-length" |
Element will be rendered in the error-max-length slot | <p> |
Parent components
ba-input-phone-number can be slotted into:
<ba‑accordion><ba‑card><ba‑card‑segmented><ba‑details><ba‑flex><ba‑form><ba‑form‑group><ba‑form‑group‑dropdown><ba‑grid>
Usage
Basic usage
<ba-input-phone-number label="Label text" name="input-phone-number" required></ba-input-phone-number>
Help text
It is sometimes useful to add hint text.
<ba-input-phone-number label="Label text" name="input-phone-number" hint-text="Custom hint text" required></ba-input-phone-number>
Priority codes
You can change the countries shown in the priority codes section of the dropdown
<ba-input-phone-number label="Label text" name="input-phone-number" hint-text="Custom hint text" priority-codes="fr,es"></ba-input-phone-number>
Validation
Note on North American Numbering Plan (NANP) dialing codes
The North American Numbering Plan (NANP) is a shared numbering system where multiple countries and territories use the same international dialing code: +1. Regions are distinguished by a three-digit area code that follows the country code.
+1 XXX XXX XXXX ↑ area code
All NANP countries are normalized to "+1" to keep the country dropdown consistent. The area code is entered as part of the phone number itself and should be handled by your phone number parsing or validation logic.
Example NANP regions include the United States, Canada, Puerto Rico, Dominican Republic, Jamaica, and Barbados.
Min/max number
You can specify a minimum and maximum length of number.
<ba-input-phone-number name="text-input" label="Input text" min-length="2" max-length="6"></ba-input-phone-number>
Required
You can set the field to be required
<ba-input-phone-number name="text-input" label="Input text" required></ba-input-phone-number>
Custom Error messages
BAgel provides error messages with translations for:
- Required
- Minimum length of numbers
- Maximum length of numbers
- Error not a number
These can be customised using slots.
<ba-input-phone-number name="text-input" label="Input text" required min-length="2" max-length="6">
<p slot="error-required">Custom required error</p>
<p slot="error-min">Custom min length error</p>
<p slot="error-max">Custom max length error</p>
<p slot="error-not-a-number">Custom not a number error</p>
</ba-input-phone-number>
Override all error messages
You can override all error messages with the error slot.
<ba-input-phone-number name="text-input" label="Input text" required min-length="2" max-length="6">
<p slot="error">This will override all error messages</p>
<p slot="error-required">Custom required error</p>
<p slot="error-min">Custom min length error</p>
<p slot="error-max">Custom max length error</p>
<p slot="error-not-a-number">Custom not a number error</p>
</ba-input-phone-number>
Custom validation
You can provide your own custom validation using events and props.
<ba-input-phone-number name="text-input" label="Input text" required>
<p slot="error">Custom error message</p>
</ba-input-phone-number>
<script>
const textInput = document.querySelector('ba-input-phone-number');
textInput.addEventListener('baOnInput', (e) => {
const value = e.detail.value;
// Do your custom validation here.
//
//
// Then set the input to invalid
textInput.setAttribute('invalid')
})
</script>