Components

Telephone

use: best-practice

The telephone component captures the many variations of phone numbers displayed on VA.gov.

Examples

Usage

When to use Telephone

When a phone number is to be shown on a page. The component can be configured to have selecting the number make a phone call, call a teletypewriter/teleprinter, or send an SMS text message.

When to consider something else

When the link text is not a phone number to be called or messaged.

How this component works

Creates a clickable phone number link. By default, phone numbers provided to this component are clickable with a link and accept a value of 3, 5, 6, or 10 digits.
Alter behavior using props. Props can be added to provide phone numbers with an extension, make them non-clickable, and to include an international phone number indicator.
Do not use a country code for US-based audiences. Use +1 only when the information is specifically addressing Veterans or people who are living outside the U.S. In other words, do not prepend a U.S. phone number with the U.S. country code unless the audience is living outside the U.S. in which case you may then use the international prop which will automatically prepend a +1.

Behavior

By default selecting the link will trigger a phone call, opening the default program on the computer or device for placing phone calls.

Choosing between variations

If the phone number should have an extension, be non-clickable, or represent an international number, additional props can be added to accommodate.
For TTY numbers, pass the tty boolean prop to have appropriate indicators in the link text and the aria-label.
For text messages, pass the sms boolean prop to have the link trigger a SMS text message instead of placing a phone call. This will open the default program on the computer or device for sending messages.

Placement

Phone numbers can appear within a sentence or on their own line.

Code usage

Attributes and Properties

Property Attribute Type Default Description

contact contact string Numeric string representing the contact number. Typical length is 3 or 10 digits - SMS short codes will be 5 or 6 digits.

countryCode country-code string Prepends the country code to the given contact number. Do NOT include the '+'

extension extension string Optional numeric string phone number extension

international international boolean false Indicates if this is a number meant to be called from outside the US. Prepends a "+1" to the formatted number.

messageAriaDescribedby message-aria-describedby string An optional message that will be read by screen readers when the phone number is focused.

notClickable not-clickable boolean false Indicates if the phone number can be clicked or not

sms sms boolean false Indicates if this is a number meant to be used to text.

tty tty boolean false Indicates if this is a number meant to be called from a teletypewriter for deaf users.

vanity vanity string Optional vanity phone number. Replaces the last 4 digits or the entire text with the vanity text input

Events

Name Description

component-library-analytics The event used to track usage of the component. This is emitted when clicking on an anchor link.

Content considerations

Using the Telephone component will apply the following formatting and accessibility guidance.

Formatting

Use hyphens between numbers, and don’t use parentheses to set off the area code: 212-123-1234.
Use +1 only when the information is specifically addressing Veterans or people who are living outside the U.S.: +1-201-123-1234.
For phone numbers with an extension, use ext. at the end: 202-123-1234, ext. 9.
Always include days and hours of operation when listing a phone number.
Use “select” to indicate the menu option after dialing a phone number. Example: Call 988 and select 1.
Use a verb ahead of the number. Use “call” or “call us at…” for phone numbers and “text” or “text us at” for text numbers.
When a phone number has (TTY: 711) included, it should be formatted in parenthesis directly following the phone number. Example: 866-440-1238 (TTY: 711) or 866-440-1238, ext. 4 (TTY: 711)

Links and aria

Hyperlink all phone numbers, including (TTY: 711). Include “TTY:” in the link. Don’t link the “call” or “text” verb that precedes the number.
Example: <a href="tel:2021231234"> 202-123-1234 </a> (<a href="tel:711">TTY: 711</a>)
New guidance as of August 2024: You no longer need to use aria labels on phone numbers or TTY. This shift came out of evolving accessibility guidance for people who use assistive technology. Teams should stop adding aria labels to phone numbers and TTY in new content, but the shift will take time to implement on existing content. If you have questions, contact the Sitewide Content, Accessibility, and Information Architecture (CAIA) team.

Note: If for some reason you cannot use the Telephone component, you are responsible for meeting the same formatting and accessibility guidance when creating links to phone numbers.

Don’t use vanity phone numbers in body copy

We don’t use vanity phone numbers in body copy, as it adds visual noise and is not helpful to screen readers. We use and hyperlink only the numeric phone number in body copy.

Exception: In marketing or promotional messaging, such as the right rail promo component, we discourage but make an exception for vanity phone numbers. In marketing or promotional components, use the format: 877-222-VETS (8387) and hyperlink the complete number including the parenthetical.

Like this

Call us toll free at 800-827-1000 (TTY: 711). We’re here Monday through Friday, 8:00 a.m. to 9:00 p.m. ET.

Accessibility considerations

By default an aria-label will be created based off of the context entered into the component and will be formatted as a combined phone number with parts within the label separated by periods, e.g. “800-555-1212” becomes “8 0 0. 5 5 5. 1 2 1 2”
If the non-clickable prop is enabled aria-hidden="true" will be added to the span element containing the number and a sr-only CSS class will be added to the span element displaying the number in the aria-label format as shown above.