Support custom country calling code in phone.number()

Clear and concise description of the problem

Description

Currently, faker.phone.number() supports different output styles through the style option:

faker.phone.number({
  style: 'international',
});

For example:

+15551234567

However, there is currently no way to explicitly specify the country calling code that should be used when generating an international phone number.

It would be useful to support a countryCode option so callers can generate phone numbers for a specific country regardless of the active Faker locale.

Proposed API

faker.phone.number({
  style: 'international',
  countryCode: '+84',
});

Example output:

+84912345678

Proposed type

number(options?: {
  /**
   * Style of the generated phone number:
   * - `'human'`: (default) A human-input phone number
   * - `'national'`: A phone number in a standardized national format
   * - `'international'`: A phone number in the E.123 international format
   * - `'mobile'`: In selected locales, provides a number used for mobile phones
   *
   * @default 'human'
   */
  style?: 'human' | 'national' | 'international' | 'mobile';

  /**
   * Country calling code to use when generating the phone number.
   *
   * Examples:
   * - `'+84'` for Vietnam
   * - `'+1'` for the United States/Canada
   * - `'+44'` for the United Kingdom
   */
  countryCode?: string;
}): string;

Example

faker.phone.number({
  style: 'international',
  countryCode: '+84',
});

Could generate:

+84912345678
+84876543210
+84345678901

Motivation

The current behavior couples the generated phone number format to the Faker locale. In some applications, the locale and the phone number's country are not necessarily the same.

For example:

faker.locale = 'en_US';

faker.phone.number({
  style: 'international',
  countryCode: '+84',
});

This would allow applications to generate Vietnamese phone numbers while keeping the rest of the generated data in the en_US locale.

This is particularly useful for:

• Testing international phone number support
• Generating test data for multiple countries
• API integration tests
• Database seed data
• Multi-country applications
• Testing phone-number validation

Open questions

1. Should countryCode only be supported with style: 'international'?
2. Should the country calling code be validated against a known list of country calling codes?
3. Should the API accept 84 as well as +84, or require the + prefix?
4. Should specifying countryCode also determine the appropriate phone-number pattern for that country?

Expected behavior

Ideally:

faker.phone.number({
  style: 'international',
  countryCode: '+84',
});

would generate a valid-looking Vietnamese international phone number, rather than simply prepending +84 to a number generated using another locale's format.

Alternatives considered

Users can currently manually prepend the country code:

`+84${faker.phone.number()}`

However, this does not guarantee that the generated number follows the numbering format of the requested country.

A first-class countryCode option would make the behavior explicit and allow Faker to generate country-specific numbers correctly.

Suggested solution

For the issue, I’d suggest presenting 2–3 possible solutions and recommending the most maintainable one.

Suggested solutions

1. Add countryCode to the existing options — Recommended

Extend the current API:

faker.phone.number({
  style: 'international',
  countryCode: '+84',
});

Faker would use the country code to select the corresponding phone-number pattern.

Example:

+84912345678
+84345678901

Advantages

• Backward compatible.
• Small API change.
• Easy to understand.
• Works naturally with the existing style option.

2. Add a country option instead of countryCode

faker.phone.number({
  style: 'international',
  country: 'vi',
});

Faker would resolve:

vi → +84 → Vietnamese phone patterns

This is arguably cleaner because Faker needs more than just the calling code to generate a correct number.

Advantages

• Country determines both calling code and phone format.
• Avoids ambiguous inputs such as +1, which is shared by multiple countries.
• Easier to support country-specific rules in the future.

Disadvantage

• The API is less explicit if the user's actual requirement is specifically controlling the calling code.

3. Support both country and countryCode

faker.phone.number({
  style: 'international',
  country: 'vi',
});

or:

faker.phone.number({
  style: 'international',
  countryCode: '+84',
});

country would be preferred for generating a country's valid phone number, while countryCode would be useful when only the calling code matters.

Recommendation

I'd recommend solution #2 (country) if Faker's internal architecture already has locale/country metadata available.

If the goal of the issue is specifically to allow users to request a calling code such as +84, then solution #1 is the simplest backward-compatible proposal:

faker.phone.number({
  style: 'international',
  countryCode: '+84',
});

But the implementation should not simply prepend +84. It should associate +84 with the appropriate Vietnamese phone-number pattern.

Alternative

No response

Additional context

No response