Components
Telephone
Use: Best practiceExamples
Default
Three Digit Number
Extension
Not Clickable
International
Aria Described By
TTY
SMS
Vanity Number
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
- By default, phone numbers provided to this component are clickable with a link and accept a value of 3, 5, 6, or 10 digits.
- Props can be added to provide phone numbers with an extension, make them non-clickable, and to include an international phone number indicator.
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
, benon-clickable
, or represent aninternational
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 thearia-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. | |
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. |
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 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:
- 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.
- 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.
- Hyperlink all phone numbers, including TTY numbers. It is not a requirement to link the “call” or “text” verb that precedes the number. We do however include “TTY” in the link and aria-label to make it clear that it’s specifically for TTY so that users who need the service see it and so those who do not do not unintentionally call a TTY number.
- Include an aria label using spaces between the digits and periods between sections in order to have screen readers read the phone number one digit at a time like a phone number, rather than as thousands or hundreds. For example:
<a href="tel:+18008271000" aria-label="8 0 0. 8 2 7. 1 0 0 0.">800-827-1000</a>
<a href="tel:711" aria-label="TTY. 7 1 1.">TTY: 711</a>
.
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. 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 enabledaria-hidden="true"
will be added to the span element containing the number and asr-only
CSS class will be added to the span element displaying the number in thearia-label
format as shown above.