Phone Input

Use a phone input to add an international phone number.

Examples

Base

Phone Number
<chi-label for="phone-input-base">Phone Number</chi-label>
<chi-phone-input id="phone-input-base"></chi-phone-input>

Placeholder

Use the placeholder attribute to provide users with an example of the type of data that can be entered into a Phone input. Note: Placeholder text is not persistent and visually disappears when a value is entered.

Phone Number
<chi-label for="phone-input-placeholder">Phone Number</chi-label>
<chi-phone-input id="phone-input-placeholder" placeholder="e.g. (123) 456-7890"></chi-phone-input>

Default Country

Use the default-country attribute to set a default two-letter country code. Defaults to "US".

Phone Number
<chi-label for="phone-input-default-country">Phone Number</chi-label>
<chi-phone-input id="phone-input-default-country" default-country="US"></chi-phone-input>

Value

Use the value attribute to set a default phone number.

Phone Number
<chi-label for="phone-input-value">Phone Number</chi-label>
<chi-phone-input id="phone-input-value" default-country="US" value="+1-6045551212"></chi-phone-input>

Excluded Countries

Use the excluded-countries attribute to set excluded countries.

Phone Number
<chi-label for="phone-input-excluded-countries">Phone Number</chi-label>
<chi-phone-input id="phone-input-excluded-countries" excluded-countries="GB,DE,FR"></chi-phone-input>

Disabled

Use the disabled boolean attribute to prevent users from interacting with the phone input. Disabled phone inputs can not receive any browsing events such as prefix selection, mouse clicks or focus.

Phone Number
<chi-label for="phone-input-disabled">Phone Number</chi-label>
<chi-phone-input id="phone-input-disabled" disabled></chi-phone-input>

Error

Use the danger state to provide feedback to users when phone number fails to validate. To meet accessibility requirements, phone input must include an error message explaining the failure and/or how to correct it.

Phone Number
<chi-label for="phone-input-error">Phone Number</chi-label>
<chi-phone-input id="phone-input-error" state="danger" helper-message="Invalid phone number"></chi-phone-input>

Input Mask

Use the input-mask boolean attribute to enter digits only in the phone input.

Phone Number
<chi-label for="phone-input-mask">Phone Number</chi-label>
<chi-phone-input id="phone-input-mask" input-mask></chi-phone-input>

Sizes

Phone input supports the following sizes: xs, sm, md (default), lg, and xl.

xs
sm
md
lg
xl
<!-- xs -->
<chi-label for="phone-input-xs">xs</chi-label>
<chi-phone-input id="phone-input-xs" size="xs"></chi-phone-input>    
<!-- sm -->
<chi-label for="phone-input-sm">sm</chi-label>
<chi-phone-input id="phone-input-sm" size="sm"></chi-phone-input>    
<!-- md -->
<chi-label for="phone-input-md">md</chi-label>
<chi-phone-input id="phone-input-md" size="md"></chi-phone-input>
<!-- lg -->
<chi-label for="phone-input-lg">lg</chi-label>
<chi-phone-input id="phone-input-lg" size="lg"></chi-phone-input>
<!-- xl -->
<chi-label for="phone-input-xl">xl</chi-label>
<chi-phone-input id="phone-input-xl" size="xl"></chi-phone-input>

Sizes

Phone input supports the following sizes: xs, sm, md (default), and lg.

xs
sm
md
lg
<!-- xs -->
<chi-label for="phone-input-xs">xs</chi-label>
<chi-phone-input id="phone-input-xs" size="xs"></chi-phone-input>  
<!-- sm -->
<chi-label for="phone-input-sm">sm</chi-label>
<chi-phone-input id="phone-input-sm" size="sm"></chi-phone-input>    
<!-- md -->
<chi-label for="phone-input-md">md</chi-label>
<chi-phone-input id="phone-input-md" size="md"></chi-phone-input>
<!-- lg -->
<chi-label for="phone-input-lg">lg</chi-label>
<chi-phone-input id="phone-input-lg" size="lg"></chi-phone-input>

Web Component

Properties

Property
Attribute
Description
Type
Default
defaultCountry
default-country
To set a default country as a two letter ISO country code
"RS" | "ME" | "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" | "LI" | "LK" | "LR" | "LS" | "LT" | "LU" | "LV" | "LY" | "MA" | "MC" | "MD" | "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" | "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"
'US'
disabled
disabled
To disable Phone input
boolean
false
dynamicValue
dynamic-value
To define dynamic value of Phone input
boolean
false
excludedCountries
excluded-countries
To define two letter ISO country codes to exclude from Phone input dropdown
string
undefined
helperMessage
helper-message
To display an additional helper text message below the Phone input
string
undefined
inputMask
input-mask
To set only numbers in the Phone Input
boolean
false
placeholder
placeholder
To define placeholder of Phone input
string
undefined
size
size
To define size of Phone input
"lg" | "md" | "sm" | "xl" | "xs"
'md'
state
state
To define state color of Phone input
"danger" | "success" | "warning"
undefined
value
value
To define value of Phone input
string
undefined

Events

Event
Description
Type
chiChange
Triggered when an alteration to the element's value is committed by the user
CustomEvent<string>
chiInput
Triggered when the user changed the element's value but did not commit the change yet
CustomEvent<string>
chiNumberInvalid
Triggered when the element's value committed by the user is an invalid phone number for the selected prefix
CustomEvent<void>

Accessibility

Keyboard Navigation

KeyFunction
TabMoves focus to the next focusable element.
Shift + TabMoves focus to the previous focusable element.
Enter,SpaceSubmits the entered value.

For comprehensive details on keyboard support, refer to our Keyboard Control Guide.

Visit WebAIM for keyboard techniques.

Guidance for developers
  • Ensure simplicity since not all browsers handle multiple labels linked to the same form element correctly.
  • Label Usage: Assign a label to each input field and make sure the for="" attribute of the label matches the id="" of the corresponding input. Remember, each id must be unique on the page, and each form element should have only one associated label.
  • Indicating Required Fields: Clearly mark required fields using indicators like an asterisk (*) or descriptive text to make them easily identifiable.
  • Help Text: Incorporate help text for all form fields, especially those with constraints. This text should be programmatically associated with the input, for example, using aria-describedby. This is particularly important for masked fields.
  • Test compatibility with various screen readers (like JAWS, NVDA, or VoiceOver) to ensure the phone input component is announced correctly. Options should be clearly read out when navigated.
  • Error Validation: Fields with validation errors should use aria-describedby to ensure that error messages are accessible to assistive technologies. If an error message has an id="my-error-message", the corresponding input should include aria-describedby="my-error-message"
Guidance for designers
  • Design with simplicity to accommodate all browsers, minimizing complexities that could hinder accessibility.
  • Obvious Required Fields: Use visual cues, such as an asterisk (*) or supplementary text, to clearly mark required fields and make them easily distinguishable.
  • User-Friendly Help Text: Place help text or examples directly below or inside the phone input field to guide users on the correct format.
  • Visible Error Feedback: Design error messages to appear clearly near the phone input field when validation fails, using color, icons, or text to make them noticeable.
  • Sufficient Tap Targets: Ensure phone input fields have large enough tap targets to accommodate users with different levels of dexterity, following touch-friendly design principles.
  • Use spacing, typography, and visual cues effectively.
  • Maintain consistency in the design of the phone input to provide a cohesive user experience.

Find live examples of accessible inputs with different types in DigitalA11y project.

Resources

Other recommendations

Explore additional accessibility tips in the general Accessibility Guide.

WCAG 2.2 Guidelines

  • Non-text Content: All non-text content that is presented to the user has a text alternative that serves the equivalent purpose. (Level A)
  • Info and Relationships: Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. (Level A)
  • Headings and Labels: Headings and labels describe topic or purpose. (Level AA)
  • Labels or Instructions: Labels or instructions are provided when content requires user input. (Level A)
  • Name, Role, Value: For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies. (Level A)