Components

Telephone Input

Use with caution: proposal English

Use the telephone input component to help users enter a telephone number.

Examples

Default

View va-input-telephone in Storybook

Mobile

View va-input-telephone in Storybook

Usage

When to use the telephone input

Collect domestic United States and international phone numbers. You can place more than one telephone input component on a page if you need to collect multiple numbers. Make each label unique.
Let users enter telephone numbers in any format familiar to them. Accept extra spaces, hyphens, brackets, and dashes. Allow country and area codes.
Only ask for a phone number if you need it.

When to consider something else

Don’t use this component if you don’t need to collect a telephone number.

How this component works

Header: The header should be clear and concise. It should describe the type of phone number you’re collecting, such as Home phone number, Mobile phone number, or Work phone number. Don’t use labels like “Primary” and “Secondary” to keep language plain.
Phone number: The component has a combo box for the country dialing code and a text input for the phone number. For these, check the usability guidance for combo boxes and text inputs.
- For the country combo box, show a flag icon, full country names, and the country code. Example: [flag icon] United States of America +1.
- Countries appear in alphabetical order, with the United States of America as the default option.
- The country list of 200+ countries comes from the libphonenumber-js library, which uses official ISO alpha-2 country codes. The list is sorted alphabetically, with the United States first.
- The United States is preselected because 99% of addresses are US-based.

Validation

By default, the telephone input component has these validation rules:

Values can’t be blank.
The phone number must match the valid pattern for the selected country code. For example: Enter a United States of America phone number in a valid format, for example, [(xxx) xxx-xxxx].
The libphonenumber library validates phone numbers.

Code usage

Attributes and Properties

Property Attribute Type Default Description

contact contact string '' The telephone contact information

country country

"LI" | "AC" | "AD" | "AE" | "AF" | "AG" | "AI" | "AL" | "AM" | "AO" | "AR" | "AS" | "AT" | "AU" | "AW" | "AX" | "AZ" | "BA" | "BB" | "BD" | "BE" | "BF" | "BG" | "BH" | "BI" | "BJ" | "BL" | "BM" | "BN" | "BO" | "BQ" | "BR" | "BS" | "BT" | "BW" | "BY" | "BZ" | "CA" | "CC" | "CD" | "CF" | "CG" | "CH" | "CI" | "CK" | "CL" | "CM" | "CN" | "CO" | "CR" | "CU" | "CV" | "CW" | "CX" | "CY" | "CZ" | "DE" | "DJ" | "DK" | "DM" | "DO" | "DZ" | "EC" | "EE" | "EG" | "EH" | "ER" | "ES" | "ET" | "FI" | "FJ" | "FK" | "FM" | "FO" | "FR" | "GA" | "GB" | "GD" | "GE" | "GF" | "GG" | "GH" | "GI" | "GL" | "GM" | "GN" | "GP" | "GQ" | "GR" | "GT" | "GU" | "GW" | "GY" | "HK" | "HN" | "HR" | "HT" | "HU" | "ID" | "IE" | "IL" | "IM" | "IN" | "IO" | "IQ" | "IR" | "IS" | "IT" | "JE" | "JM" | "JO" | "JP" | "KE" | "KG" | "KH" | "KI" | "KM" | "KN" | "KP" | "KR" | "KW" | "KY" | "KZ" | "LA" | "LB" | "LC" | "LK" | "LR" | "LS" | "LT" | "LU" | "LV" | "LY" | "MA" | "MC" | "MD" | "ME" | "MF" | "MG" | "MH" | "MK" | "ML" | "MM" | "MN" | "MO" | "MP" | "MQ" | "MR" | "MS" | "MT" | "MU" | "MV" | "MW" | "MX" | "MY" | "MZ" | "NA" | "NC" | "NE" | "NF" | "NG" | "NI" | "NL" | "NO" | "NP" | "NR" | "NU" | "NZ" | "OM" | "PA" | "PE" | "PF" | "PG" | "PH" | "PK" | "PL" | "PM" | "PR" | "PS" | "PT" | "PW" | "PY" | "QA" | "RE" | "RO" | "RS" | "RU" | "RW" | "SA" | "SB" | "SC" | "SD" | "SE" | "SG" | "SH" | "SI" | "SJ" | "SK" | "SL" | "SM" | "SN" | "SO" | "SR" | "SS" | "ST" | "SV" | "SX" | "SY" | "SZ" | "TA" | "TC" | "TD" | "TG" | "TH" | "TJ" | "TK" | "TL" | "TM" | "TN" | "TO" | "TR" | "TT" | "TV" | "TW" | "TZ" | "UA" | "UG" | "US" | "UY" | "UZ" | "VA" | "VC" | "VE" | "VG" | "VI" | "VN" | "VU" | "WF" | "WS" | "XK" | "YE" | "YT" | "ZA" | "ZM" | "ZW"

this.DEFAULT_COUNTRY The 2 letter ISO country code for a country

error error string '' The error for the component

header header string 'Primary phone number' Header text for the component

hint hint string Hint string text

noCountry no-country boolean false Whether the country select should be included. Set to true to exclude it.

required required boolean false Render marker indicating field is required.

Events

Name Description

vaContact The event emitted when the contact changes

Content considerations

Content for both variations can be found in Ask users for… Phone numbers pattern.

Accessibility considerations

Keyboard navigation: Users can tab to the combo box. Use the Arrow keys to move through the country dropdown options. Press Enter to select a country. Focus returns to the combo box field. Users can then tab to the text input to enter a phone number.
Focus indicator: A clear outline appears when the input field or dropdown has focus.
Screen readers: The combo box is announced as “Country code” with the current selected country (for example, “United States +1”). The phone number input is announced as a text input field. For error states, screen readers announce the error message when it appears.
Alt text for flags: The flags in the combo box are decorative, so the alt text is undefined.
Error prevention and feedback: Real-time validation gives clear feedback when input is invalid. This prevents submission until a valid phone number is entered.

Component checklist

Maturity

Guidance: Examples, usage, code usage, content considerations, and accessibility considerations are all complete.
Research: VFS team conducted research on this component which is linked from this page.
Stability: Component has been in production for more than 3 months with no significant issues found.
Adoption: Multiple teams have adopted this component.; Note: This component was introduced in June 2025.

Accessibility

While this component has been previously tested against older criteria, it has not yet been audited with the updated testing criteria.

Code assets

Variations: Storybook includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive: Component depicted in all responsive breakpoints.
Interactive states: Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens: All design attributes (color, typography, layout, etc.) are available as tokens.
Internationalization: Describes i18n attributes.

Visual assets

Variations: Figma library includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive: Component designed to work in all responsive breakpoints.
Interactive states: Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens: All design attributes (color, typography, layout, etc.) are available as tokens.

70% complete (7 of 10)

Legend:

Complete
Incomplete
Not applicable