Meet v2. Smaller bundle. Same familiar API.

A SMALL PLUGIN. A WORLD OF NUMBERS.

Phone numbers.
Validated.

Give your Yup schemas a phone check that understands the world. One method, familiar chaining, and full phone metadata.

npm install yup yup-phone
Yup 0.32 + 1.x TypeScript ready MIT licensed

THE PLAYGROUND

Try a phone number.

Live

National, international, formatted, or vanity. Try them all.

Validation mode

Require the number to match the selected region.

Try:

Uses a lazy schema. The default phone check rejects empty values.

Loading validator…

The demo runs locally in your browser.

Your schema
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

A familiar fit.
A tiny API.

Import the plugin once, then add .phone() to your string schema. Yup stays your application’s peer dependency.

01 / INSTALL

Add it to your project.

npm install yup yup-phone

Already using Yup 0.32? Keep it:

npm install yup@0.32.11 yup-phone@2View on npm
02 / USE IT
import * as yup from 'yup';
import 'yup-phone';

const phone = yup.string().phone('US', true);

phone.isValidSync('(415) 555-2671');
// → true. That’s it.

Side-effect import. Familiar Yup chaining. Built-in declarations.

THE ENTIRE PHONE API

Three arguments.
You’re in control.

Choose a parsing region, decide how strictly to match it, and customize your error message.

schema.phone(countryCode?, strict?, errorMessage?)Returns the same schema
01

countryCode

string · default 'IN'

The parsing region for national numbers. International numbers keep their own calling code.

.phone('GB')
02

strict

boolean · default false

When enabled, checks the selected region’s rules and calling code. Loose mode accepts valid international numbers.

.phone('US', true)
03

errorMessage

string · optional

Your own Yup error message, with support for path interpolation.

.phone('US', true, 'Invalid phone')

LESS TO SHIP

A lighter bundle.
Full phone metadata.

The v2 migration reduced the minified UMD gzip footprint by about 55%, while retaining max metadata and the original validation tests.

Explore the measured benchmarks
Minified UMD · gzipv2.0.0 release
v1.3.2111.6 kB
v2.0.049.7 kB

Measured artifact sizes, not a guarantee of faster validation for every workload. The full report includes timing results.

THE USEFUL DETAILS

A few things
worth knowing.

Ask a question
Does v2 work with my existing Yup version?

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.

What is the difference between strict and loose?

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.

How do I make a phone field optional?

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.

Why is .phone missing from my schema?

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.

How do I keep my required-field error message?

Put required before phone:

yup.string()
  .required('Phone is required')
  .phone('US');

This order makes the required message win for an empty string.

Where can I find release and security information?

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.

One more check.
A better form.

Add phone validation to the Yup schemas you already know.

Get started