Components

Input phone

Form input for phone number text, including country and other identifying codes

Overview

  • Available since: Paris
  • A11Y: WCAG 2.1 AA

Input phone is designed specifically for phone number entries. It often includes formatting assistance to help users enter their phone numbers in the correct international or local format.

ServiceNow link
Input phone code documentation

UIB and developer guidance

Figma link
Input phone Figma component

Horizon components and styles library

Loading playground

When to use

Use input phone when you need users to provide their phone numbers, whether for contact information or verification purposes.

When not to use

Don’t use an input phone if the expected data is not a phone number.

Anatomy

Learn about the individual parts of input phone

Input phone field

anatomy of the phone number input field
  1. Label: Text that describes the expected user input; a label must be present for accessibility, either as the component's label element or external to the component
  2. Required indicator (optional): Field decorator that shows if a field is required
  3. Information button (optional): Opens a popover and shows the field helper text
  4. Phone button (optional): Allows users to execute a call when the field contains an phone number
  5. Input field: Area for entering the phone number
  6. Value: Text entered by a user
  7. Country code (optional): Number prefix that's unique to each country

Input phone field dropdown

anatomy of the dropdown panel for phone number input field
  1. Dropdown trigger: Opens and closes the dropdown panel
  2. Search field (optional): Takes in a search query and highlights matching values
  3. Dropdown list: Displays a list of countries and their associated country codes
  4. List item: Text label that displays a country name followed by the country code numerals; these list items are alphabetized in the dropdown panel; when an list item is selected, only the country code is displayed

Subcomponents

See usage guidance for icon

See usage guidance for dropdown

Usage

Use Input Phone to display a phone number that the user can call by selecting the phone button.

asterisk next to the label to show that the field is required

When the user hovers over the asterisk, a tooltip appears and displays "Required"

Input Phone can also be blank, allowing the user to enter a phone number and either save or call that number.

phone number input field in a form for a user submitted incident

Variants

Learn about the attributes of Input Phone.

Types

Input Phone is only one type of the input field component.

See usage guidelines for input

See usage guidelines for input password

See usage guidelines for input URL

See usage guidelines for textarea

Sizes

Input Phone has two sizes: small (sm) and medium (md). Choose a size that fits with your display and complements the surrounding content. Remember to choose a size that supports the length of the expected user input, including any labels or decorators.

Small

Use the small size for areas that have limited space. The small size reduces the font size of the text.
If icons are included in the input field slot, the padding is reduced between multiple icons.

Medium

Use the medium size alongside similarly sized components and content.

Note: Medium is the default size for input phone.

Configurations

Learn how to customize Input Phone by configuring the available properties.

Placeholder text

You can add placeholder text to provide users with guidance on the type of input and expected format. The placeholder text disappears when the user enters a number.

In this example, the placeholder text includes the country code +555 and the phone number (555) 555-5555.

In this example, the placeholder text includes the country code +1 and the example phone number (555) 555-5555

Required indicator

You can configure an input field as required with an asterisk indicator after the form label. This indicates that the user must enter a value in this field.
Note: This indicator shouldn’t be used with the optional field indicator.

phone number and a phone icon button that the user can select to call that number

Optional indicator

You can configure an input field as optional. When used, optional fields display "(Optional)" text next to the label. Add this indicator to an optional field when all other fields are required by default. However, you can show the user that a field is optional without displaying the indicator at all.
Note: This indicator shouldn’t be used with the required field indicator.

Shows an input phone field marked as optional

Field helper text

Use the field helper text to display information needed for guiding users on how to complete the field. The helper text will display in a popover when the information icon is activated.

Country codes

If your use case requires users to enter phone numbers outside of the US, you can configure country codes to be displayed in a dropdown. Selecting a country from the dropdown list will display the country code in the input.

dropdown panel where the user can select a country to choose its country code

In this example, the user selected the dropdown trigger to reveal all possible country codes

Design recommendations

Learn how to use input phone in your design.

Alignment and positioning

The text aligns to the left within the input field.

If you include a dropdown panel, the list item in the dropdown list align to the left.

list of phone number country codes in the open dropdown panel

UI text guidelines

These are some recommendations for using text within input phone.

Labels

  • Use a label that tells the person that this input is for phone numbers only

Form field messaging

  • Informational message
    • Use clear and concise language to help the person fill out the input
      • For example, “Remember to include the country code.”
  • Warning message
    • Include information that helps the person understand any consequences or next steps
    • Use present tense since this message shows up before any input
      • For example, “Avoid using dashes between numbers.”
  • Error message
    • Avoid blaming the person. Instead, tell them what happened and how they can fix it.
    • Use past tense since this message shows up after the person submits something
      • For example, “Failed to verify this phone number.”

Field helper text

  • Provide additional information about password requirements to help the person understand what they're expected to input
  • If you’re adding a list into the popover, consider formatting it using bullets to make it easier to read

Placeholder text

  • Use sparingly because it will disappear once the person puts their cursor in the input field
  • Format placeholder text as an example of a phone number or a brief description of how to complete the field

For additional UI text guidelines, visit the usage guidance for the input component.

Behavior

Learn how input phone behaves when the display changes or a user interacts with the component.

States

Input phone has the following states: default, hover, focus, disabled, read only and invalid.
A read-only state shows a number that the user can't change, update, or call directly. For example, input phone may be in a read-only state if the employer assigned a specific phone number to the employee.

State Normal
Default now-input-phone
Hover now-input-phone
Focus now-input-phone
Read-only now-input-phone
Disabled now-input-phone
Invalid now-input-phone

Responsive behaviors

Input phone resizes based on the width of its container.

Interactions

Learn how Input phone responds when a user interacts with it.

Invalid state

If a user enters an invalid phone number and navigates away from the input, the input state will change to invalid. Similarly, bypassing a required input will result in the state changing to invalid. In either case, the input will remain invalid until corrected. When in an invalid state, both the label and the asterisk—or optional text, if configured—will appear in red.

The input phone field in an invalid state, showing a message telling the user what caused the error

Phone button

The user can enter a phone number and call that number directly by selecting phone icon in the input field.

phone number with the ability to call that number by selecting the phone icon

Information button

If you’ve configured field helper text, a user can select the information icon to view additional information or suggestions for the expected input.

hovering over the information icon to display a tooltip with helper text

When Country Codes have been configured, the dropdown will be displayed at the start of the input. Selecting the dropdown will trigger a dropdown list. Selecting a list item will only display the country code in the dropdown.

dropdown panel where the user can select a country to choose its country code

In this example, the user selected the dropdown trigger to reveal all possible country codes

Usability

Input phone complies with all internationalization and accessibility requirements.

Internationalization

When the display translates to a right-to-left (RTL) language, the content flips and aligns on the right. The phone icon appears on the left instead of the right side, and all list items within the dropdown list align to the right.

phone number input field reading right-to-left, with label on right and phone icon on left

Accessibility

Learn how to access the actionable elements of input phone through keyboard interactions and screen readers.

Keyboard interactions

You can access the actionable elements of input phone with these keyboard keys:

  • Tab: Follows the Tab order within the input field and moves from the country code to the phone number
  • Tab or Shift + Tab: Moves between the interactive elements on the input field in the standard tab order; if the component includes a dropdown, it appears in the tab order after the country code
phone number input field in the focus state

When focus is in the text input field:

  • Arrow right/left: Moves the text entry caret across available text
  • Arrow up/down: Moves the text entry caret through rows of available text (if applicable)
  • Control/Command + Shift: Selects text
  • Shift + Arrow right/left: Selects one character at a time

When focus is in the dropdown panel:

  • Enter or Space: Selects the currently focused menu item and closes the dropdown panel
  • Down arrow: Moves focus to the next non-disabled menu item
  • Up arrow: Moves focus to the previous non-disabled menu item
  • Home: Moves focus to the first non-disabled menu item
  • End: Moves focus to the last non-disabled menu item
  • Esc: Closes the dropdown panel without making a selection

Screen readers

When you apply ARIA labels to a component, screen readers announce the controls and content of input phone in the prescribed tab order.

  • Assign the aria-label or aria-labeledby attribute to input field to allow screen readers to provide additional context for that form field
  • Assign the aria-describedby attribute to contents of field helper; this provides supplementary user guidance for the content required in the input field
  • Assign the aria-required to required field indicator and set to "true"; By default, aria-required is set to "false"
  • Assign the aria-invalid to "true" to alert when a field is marked as returning an error; by default, aria-invalid is set to "false"