Phone numbers on a document somebody has to dial from abroad

The defect

National formats drop the country code and often add a trunk digit that has to be removed when dialling internationally. Printed on a document that leaves the country, such a number is not dialable and, worse, is not obviously undialable: the reader tries it, it fails, and there is nothing on the page that tells them what to prepend or which digit to drop. Grouping is the second half of the problem. A number printed as an unbroken run of eleven or twelve digits is hard to read and hard to transcribe, and the grouping conventions that make it readable differ by country.

What it does to the document

The international form is longer than the national one, so a contact block laid out for the short form wraps once the country code goes in. It belongs in the contact block alongside the email address, where the same nowrap and overflow rules apply for the same reason.

The decisions

Reasons rather than a description of the code. Formatting rules are data that changes, so most of these are about taking the rule from a maintained source rather than encoding today's answer.

• Print in the international form with the country code, for any document that might be read outside the country. It is dialable everywhere and unambiguous.
• Store in a canonical international form and format for display, rather than storing whatever was typed.
• Group the digits for readability using a library that knows the destination's convention, rather than inserting spaces at a fixed interval.
• Keep the whole number unbreakable. A phone number split across a line is routinely dialled wrong.
• Where an extension exists, separate it clearly and label it, because an extension run onto the end of the number is dialled as part of it.
• Do not print a national and an international form of the same number side by side. Two numbers that look different are two numbers to a reader in a hurry.

In code

The formatting happens before the markup exists, so this is mostly code rather than CSS. The wrong version is kept in a comment where the wrong version is the thing people write.

// Store canonical, format for display.
const stored = "+441144960022";        // canonical, international

// International form, grouped for the destination's convention.
// Use a phone-number library rather than inserting spaces at a fixed
// interval, because grouping conventions differ by country.
const display = formatInternational(stored);   // e.g. "+44 114 496 0022"

/* Keep it unbreakable and set it in a face where the digits are
   unambiguous, because this is a transcribed field:

   .tel {
     white-space: nowrap;
     font-variant-numeric: tabular-nums;
   }

   Extension separated and labelled, never run onto the end:
   <span class="tel">+44 114 496 0022</span> ext. 214                 */

What people do instead

Printing the number exactly as it was typed into the system. Different records then carry different formats, some with country codes and some without, and the document ends up with two contact numbers in visibly different shapes on the same page.

How to find out rather than assume

Take the number off a printed copy and dial it from another country. If it does not connect, or if you had to work out what to add, the format is wrong. Then confirm it did not wrap at the narrowest column it appears in.

Where the API sits in this

Nowhere, and that is worth saying plainly. This API renders HTML to PDF. By the time markup reaches it, every value in it is already a string that somebody's code produced, so there is no locale option on the render because there would be nothing for one to do. What the render controls is the page: the size, the margins, and whether the formatted value still fits the column it landed in. That is why each of these pages has a paragraph about the layout consequence, because that is the half a document adds to the general problem.

Frequently asked

Related formatting topics

The defects that travel together, then the rest of the same group.