Skip to content

Valibot

Developer UtilitiesValidationTypeScript
Official docs ↗GitHub ↗

What it is

Valibot is a schema validation library with an API similar to Zod's but built around tree-shakeable functions, producing dramatically smaller client bundles.

Schemas are composed from imported functions rather than chained methods. The mental model matches Zod closely, so migration is mostly mechanical.

Installation

npm install valibot

Getting started

The smallest useful thing you can do with it, and what each part means.

Function composition instead of chaining
import * as v from 'valibot';

const UserSchema = v.object({
  id: v.pipe(v.number(), v.integer(), v.minValue(1)),
  email: v.pipe(v.string(), v.email()),
  role: v.picklist(['admin', 'member']),
});

type User = v.InferOutput<typeof UserSchema>;

const user = v.parse(UserSchema, input); // throws on failure
v.pipe replaces Zod's chaining. Because each validator is a separate import, a bundler includes only what you actually reference.
Non-throwing validation
const result = v.safeParse(UserSchema, input);

if (!result.success) {
  const messages = v.flatten(result.issues).nested;
  return { errors: messages };
}

use(result.output);
The shape mirrors Zod's safeParse, which is deliberate — the library is designed so the migration is largely find-and-replace.

Advanced usage

Where the library earns its place over a simpler alternative.

Transforms and custom checks
const Signup = v.pipe(
  v.object({
    password: v.pipe(v.string(), v.minLength(12)),
    confirm: v.string(),
  }),
  v.forward(
    v.check((data) => data.password === data.confirm, 'Passwords must match'),
    ['confirm'],
  ),
);

const Timestamp = v.pipe(
  v.string(),
  v.isoTimestamp(),
  v.transform((s) => new Date(s)),
);
v.forward is the equivalent of Zod's `path` option — it attaches a cross-field error to the specific field the user needs to correct.

Errors and fixes

The failures you are most likely to hit, and what actually resolves them.

Types are wrong after adding a transform
Use v.InferOutput for the post-transform type. InferInput describes what goes in.
Ecosystem integrations expect Zod
Many libraries accept Standard Schema now, which Valibot implements. Otherwise check for a Valibot-specific adapter.

Best practices

  • Choose Valibot over Zod when client bundle size is a real constraint; choose Zod for its larger ecosystem.
  • Import as a namespace (import * as v) — the docs assume it and it keeps schemas readable.
  • Use InferOutput, not InferInput, when the schema has transforms; they differ.
  • Validate at boundaries only, as with any schema library.

Background

Why it exists, and what it was reacting to.

Created by Fabian Hiller, Valibot addresses Zod's main weakness in the browser: because Zod is method-chained on a class, bundlers cannot drop the parts you do not use. Valibot's standalone functions can be tree-shaken to a fraction of the size.

Related libraries

Others in Developer Utilities for TypeScript.

← All TypeScript librariesTypeScript guide