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: 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
Edit this page in GitHub (Permissions required)
Last updated: Jun 04, 2025