Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Components

Telephone Input

Use with caution: candidate English
Use the telephone input component to help users enter a telephone number.

Examples

Default

View va-telephone-input in Storybook

Mobile

View va-telephone-input in Storybook

Usage

Only ask for a phone number if you need it.

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.

When to consider something else

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

How this component works

  • Label: The label 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 hint hint string Hint string text label label string 'Home phone number' Label text for the component 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. showInternalErrors show-internal-errors boolean true If true, this prop instructs the component to display error messages in response to the internal error state. If false, error messages must be passed in from consumer.

Events

Name Description vaContact The event emitted when the contact changes

Event payload

Whenever the component is modified it emits a vaContact event that includes the following properties:

  • contact: the national phone number the user entered, e.g. 2345678910
  • countryCode: the two letter ISO country code for the country the user selected, e.g. US
  • callingCode: the prefix for the country the user selected, e.g. 1

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.

Accessibility

For more information on each category, see Accessibility testing for design system components.

Last audit date
2025-06-06
Code review
Pass
Readability
Pass
Automated scans
Pass
Use of color
Pass
Text resizing, zoom, and magnification
Pass
Screen readers
Pass
Input and interaction methods
Pass

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.
100% complete (7 of 7)

Legend:

  • Complete
  • Incomplete
  • Not applicable
Edit this page in GitHub (Permissions required)
Last updated: Jun 23, 2025