Components
Telephone Input
Use with caution: proposalExamples
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
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
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.
Related
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.
Legend:
-
Complete -
Incomplete -
Not applicable