countryCode
string · default 'IN'
The parsing region for national numbers. International numbers keep their own calling code.
.phone('GB')
A SMALL PLUGIN. A WORLD OF NUMBERS.
Give your Yup schemas a phone check that understands the world. One method, familiar chaining, and full phone metadata.
THE PLAYGROUND
National, international, formatted, or vanity. Try them all.
Require the number to match the selected region.
Uses a lazy schema. The default phone check rejects empty values.
The demo runs locally in your browser.
yup.string().phone('US', true)
Fits your existing schemaYup 0.32.11 and 1.x, with chainable types.
Beyond a regular expressionCountry rules from libphonenumber-js/max.
Works where you buildESM, CommonJS, UMD, and TypeScript.
FROM INSTALL TO VALIDATION
Import the plugin once, then add .phone() to your
string schema. Yup stays your application’s peer dependency.
npm install yup yup-phone
Already using Yup 0.32? Keep it:
npm install yup@0.32.11 yup-phone@2View on npm
import * as yup from 'yup';
import 'yup-phone';
const phone = yup.string().phone('US', true);
phone.isValidSync('(415) 555-2671');
// → true. That’s it.
const yup = require('yup');
require('yup-phone');
const phone = yup.string().phone('US', true);
phone.isValidSync('(415) 555-2671');
// → true. Same API, different import.
import * as yup from 'yup';
import 'yup-phone';
const schema = yup.object({
phone: yup.string().required().phone('US', true),
});
type Contact = yup.InferType<typeof schema>;
// { phone: string } — types stay intact.
Side-effect import. Familiar Yup chaining. Built-in declarations.
THE ENTIRE PHONE API
Choose a parsing region, decide how strictly to match it, and customize your error message.
schema.phone(countryCode?, strict?,
errorMessage?)Returns the same schema
string · default 'IN'
The parsing region for national numbers. International numbers keep their own calling code.
.phone('GB')
boolean · default false
When enabled, checks the selected region’s rules and calling code. Loose mode accepts valid international numbers.
.phone('US', true)
string · optional
Your own Yup error message, with support for path interpolation.
.phone('US', true, 'Invalid phone')
Need optional fields, default-country rules, or browser-script setup?
Read the complete guideLESS TO SHIP
The v2 migration reduced the minified UMD gzip footprint by about 55%, while retaining max metadata and the original validation tests.
Explore the measured benchmarksMeasured artifact sizes, not a guarantee of faster validation for every workload. The full report includes timing results.
Yes, the declared peer range is ^0.32.11 || ^1.0.0.
The original phone tests remain unchanged. Version 2 requires Node
18+ and modern browsers with ES2020 support.
Loose mode uses the region to parse national numbers, while allowing valid international numbers from other regions. Strict mode additionally checks the selected region’s rules and calling code. Try the International example, then toggle Strict region in the playground.
The default phone check still rejects empty strings, undefined, and null. To allow blank values, apply it only when a value is present:
const optionalPhone = yup.lazy((value) =>
value == null || value === ''
? yup.string().nullable()
: yup.string().phone('US')
);
The playground’s Allow empty values option demonstrates this explicit workaround.
Import 'yup-phone' before constructing the schema,
and keep one supported Yup instance in your application. The
package registers its method on your application’s peer
dependency. TypeScript users should use Yup’s built-in
declarations and remove obsolete @types/yup.
Put required before phone:
yup.string()
.required('Phone is required')
.phone('US');
This order makes the required message win for an empty string.
See the releases and benchmark artifacts and the release setup guide. GitHub Actions checks compatibility, package formats, dependency audits, and CodeQL. Versioned npm releases include provenance.
Add phone validation to the Yup schemas you already know.