Yup — Schema Validation for JavaScript Objects

Introduction

Yup provides a declarative way to define validation schemas for JavaScript objects. Rather than writing imperative if-else checks, developers describe the shape and constraints of their data once, and Yup handles parsing, coercion, and error message generation. Its API is heavily inspired by Joi but designed for browser and frontend use.

What Yup Does

• Defines object schemas with chainable type-safe validation rules
• Validates and coerces values at runtime with detailed error messages
• Supports async validation for server-side checks like unique email verification
• Provides conditional validation via when() for fields that depend on other fields
• Generates TypeScript types from schemas via InferType

Architecture Overview

Yup schemas are immutable builder objects. Each method call (string(), required(), min()) returns a new schema instance with the added constraint. On validate(), Yup walks the schema tree, applies type coercion (e.g., string to number), runs each test, and collects errors. Errors are returned as a ValidationError with a path, message, and type for each failing field. AbortEarly controls whether validation stops at the first error or collects all.

Self-Hosting & Configuration

• Install via npm as a frontend or backend dependency — no server infrastructure needed
• Configure default error messages globally with yup.setLocale()
• Use abortEarly: false to collect all validation errors at once
• Enable stripUnknown to remove fields not defined in the schema
• Pair with Formik or React Hook Form resolvers for seamless form integration

Key Features

• Chainable fluent API for building readable validation rules
• Built-in validators for strings, numbers, dates, arrays, booleans, and objects
• Conditional schemas with when() and context-dependent validation
• Custom test methods via .test() for application-specific rules
• TypeScript InferType extracts static types from runtime schemas

Comparison with Similar Tools

• Zod — TypeScript-first with stricter type inference; Yup has broader ecosystem integration with form libraries
• Joi — richer validation features for Node.js; Yup is lighter and designed for browser use
• Valibot — tree-shakeable modular design; Yup offers a more established API and larger community
• Superstruct — composable validation with custom types; Yup has more built-in validators
• AJV — JSON Schema-based validation; Yup uses a programmatic builder pattern instead of schema files

FAQ

Q: How do I use Yup with React Hook Form? A: Install @hookform/resolvers and pass yupResolver(schema) as the resolver option to useForm(). Yup will validate inputs on every submission or change.

Q: Can Yup validate nested objects? A: Yes. Use yup.object().shape() for nested structures. Each nested object can have its own schema with full validation rules.

Q: Does Yup support async validation? A: Yes. Use .test() with an async function for validations that require API calls, such as checking if a username is already taken.

Q: What is the difference between validate and cast? A: validate() checks constraints and throws on failure. cast() applies coercion and transforms without running validation tests, useful for normalizing data before processing.

Sources

• https://github.com/jquense/yup
• https://github.com/jquense/yup#readme