Patterns: Create a user profile

Phone number

Help users to enter their phone number or numbers to ensure effective communication.

The phone number pattern allows users to easily enter their phone number and ensures the phone number is properly formatted.

About this pattern

What problem does this solve?

People format their phone number in varying ways — with or without extra spaces, hyphens, periods, and parentheses. Some may be more accustomed to providing only seven digits. This pattern was designed to reduce confusion and frustration and ensure accurate entry.

When to use this pattern

Use this pattern if you need to collect the user’s phone number. Only ask for the phone number if you need it. This pattern is designed to support U.S. phone numbers and their specific format.

What’s the solution?

Help users enter their phone numbers in a consistent, correct, usable format. Use the form label and hint text to show users the expected format, and if you specifically need a U.S. or SMS-capable mobile phone number. When possible, use input masking and both client- and server-side validation to ensure the phone number they enter can be successfully used to contact them if needed.

Guidance

What to do

  • Tell users why you need their phone number, why you might contact them, and when.
  • Do clearly state if you need a U.S. telephone number.
  • Do clearly state if you need an SMS-capable mobile phone number, such as when you need to text a security code for validation.
  • Use clear hint text and input masking to ensure proper formatting.
  • Do use a "text" vs "numeric" input type.
  • Do use fieldset and legend to group related radio buttons together, and clear labels and attributes on these form elements.
  • Consider using the autocomplete attribute on telephone number inputs, to allow the browser to autofill information if it has been previously entered.
  • Offer very clear validation messages to help users successfully meet format requirements.
  • Allow a user to supply multiple phone numbers, labeling options Primary and Secondary.
  • Consider offering an extension field for a business line or other temporary residences/shelters.
  • Do consider the safety implications of users who share phones and voicemail boxes. Ask for permission to leave potentially sensitive messages.

What not to do

  • Do not require users to enter hyphens or other characters.
  • Do not split the phone number into separate fields. Separate fields have a high user interaction cost
  • Do not assume that voicemail boxes are private unless explicitly stated through permission-based settings or in the message itself.
Phone number
10-digit, U.S. only, for example 999-999-9999
Potentially sensitive information
10-digit, U.S. only, for example 999-999-9999
Potentially sensitive information 
<fieldset class="usa-fieldset">
  <legend class="usa-legend usa-legend--large">Phone number</legend>
  <label class="usa-label" for="tel-number">Primary phone number</label>
  <div class="usa-hint" id="primaryPnHint">10-digit, U.S. only, for example 999-999-9999</div>
  <input class="usa-input margin-bottom-1" id="tel-number" name="tel-number" type="tel" aria-describedby="primaryPnHint"/>
  <fieldset class="usa-fieldset">
    <legend class="usa-legend usa-legend">Potentially sensitive information</legend>
    <div class="usa-radio">
      <input class="usa-radio__input" id="primary-yes-info" type="radio" name="primary-sensitive-info" value="primary-yes-info"/>
      <label class="usa-radio__label" for="primary-yes-info">Yes, you may leave sensitive information in voicemail or text message</label>
    </div>
    <div class="usa-radio">
      <input class="usa-radio__input" id="primary-no-info" type="radio" name="primary-sensitive-info" value="primary-no-info"/>
      <label class="usa-radio__label" for="primary-no-info">No, please do not leave sensitive information in voicemail or text messages</label>
    </div>
  </fieldset>
  <label class="usa-label" for="secondary-tel-number">Secondary phone number</label>
  <div class="usa-hint" id="secondaryPnHint">10-digit, U.S. only, for example 999-999-9999</div>
  <input class="usa-input margin-bottom-1" id="secondary-tel-number" name="secondary-tel-number" type="tel" aria-describedby="secondaryPnHint" />
  <fieldset class="usa-fieldset">
    <legend class="usa-legend usa-legend">Potentially sensitive information</legend>
    <div class="usa-radio">
      <input class="usa-radio__input" id="secondary-yes-info" type="radio" name="secondary-sensitive-info" value="secondary-yes-info"/>
      <label class="usa-radio__label" for="secondary-yes-info">Yes, you may leave sensitive information in voicemail or text
        message</label>
    </div>
    <div class="usa-radio">
      <input class="usa-radio__input" id="secondary-no-info" type="radio" name="secondary-sensitive-info" value="secondary-no-info" />
      <label class="usa-radio__label" for="secondary-no-info">No, please do not leave sensitive information in voicemail or text
        messages</label>
    </div>
  </fieldset>
</fieldset>
<fieldset class="usa-fieldset">
  <legend class="usa-legend usa-legend--large">Phone number</legend>
  <label class="usa-label" for="tel-number">Primary phone number</label>
  <div class="usa-hint" id="primaryPnHint">10-digit, U.S. only, for example 999-999-9999</div>
  <input class="usa-input margin-bottom-1" id="tel-number" name="tel-number" type="tel" aria-describedby="primaryPnHint"/>
  <fieldset class="usa-fieldset">
    <legend class="usa-legend usa-legend">Potentially sensitive information</legend>
    <div class="usa-radio">
      <input class="usa-radio__input" id="primary-yes-info" type="radio" name="primary-sensitive-info" value="primary-yes-info"/>
      <label class="usa-radio__label" for="primary-yes-info">Yes, you may leave sensitive information in voicemail or text message</label>
    </div>
    <div class="usa-radio">
      <input class="usa-radio__input" id="primary-no-info" type="radio" name="primary-sensitive-info" value="primary-no-info"/>
      <label class="usa-radio__label" for="primary-no-info">No, please do not leave sensitive information in voicemail or text messages</label>
    </div>
  </fieldset>
  <label class="usa-label" for="secondary-tel-number">Secondary phone number</label>
  <div class="usa-hint" id="secondaryPnHint">10-digit, U.S. only, for example 999-999-9999</div>
  <input class="usa-input margin-bottom-1" id="secondary-tel-number" name="secondary-tel-number" type="tel" aria-describedby="secondaryPnHint" />
  <fieldset class="usa-fieldset">
    <legend class="usa-legend usa-legend">Potentially sensitive information</legend>
    <div class="usa-radio">
      <input class="usa-radio__input" id="secondary-yes-info" type="radio" name="secondary-sensitive-info" value="secondary-yes-info"/>
      <label class="usa-radio__label" for="secondary-yes-info">Yes, you may leave sensitive information in voicemail or text
        message</label>
    </div>
    <div class="usa-radio">
      <input class="usa-radio__input" id="secondary-no-info" type="radio" name="secondary-sensitive-info" value="secondary-no-info" />
      <label class="usa-radio__label" for="secondary-no-info">No, please do not leave sensitive information in voicemail or text
        messages</label>
    </div>
  </fieldset>
</fieldset>

Considerations

  • Confirm you need this information. As with all personal information, consider whether you need to collect it at all. Clearly explain the reason for asking for the information and what will be done to secure the user’s privacy.
  • Notifications. If the phone number will be used to subscribe the user to any type of follow-up calls, including automated notifications, reminders, or informational call lists, clearly inform the user and provide a way for the user to opt out.
  • Sensitive information. If you plan on using the phone number to follow up with the user, consider whether you need to ask the user for permission to leave a voice or text message, and ask them whether sensitive information can be included in the message. Some users may not want sensitive information left in messages for privacy or safety reasons.

Usability guidance

  • Consider using an input mask. In fields with a specific expected format, an input mask allows you to constrain and shape the information being entered into that format, without impairing the user’s ability to copy/paste or correct mistyping. If you use an input mask to support formatting the phone field, it should be ___-___-____ for U.S. phone numbers so that the phone number maps to users’ experience and is properly formatted. Input masks can help a user more confidently fill out restricted fields, reduce user anxiety about making a mistake, and reduce validation errors and web form abandonment, particularly on mobile devices.
  • Validate client-side and server-side if possible. Use client-side and ideally server-side validation to ensure proper formatting and usable phone numbers.
  • This pattern uses radio buttons. See usability guidance for radio buttons.

Accessibility

  • Follow input guidance. These text fields should follow the accessibility guidelines for all text inputs.
  • Use “text” instead of “number” inputs. Research indicates that numeric inputs still carry many usability problems. The way the user enters the data may differ from what the browser expects. Use <input type="text" inputmode="numeric" pattern="[0-9]*"> to better support mobile users.
  • Use fieldset and legend. Group related radio buttons together with <fieldset> and describe the group with <legend>.
  • Use proper labels and attributes. Each radio button should have a <label>. Associate the two by matching the label’s for attribute to the input’s id attribute.
  • Customization. As you customize, make sure you follow accessibility guidelines for form templates and the accessibility guidelines for form controls.

References

Disclaimer

Links to nongovernment sources are made for educational or source citation purposes only, and do not represent an endorsement of the organizations by the General Services Administration. The General Services Administration does not assume any responsibility for the content, operation, or policies of other entities’ websites.

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2022-11-14 3.3.0
  • Guidance
 No

Pattern published.