How to do cross-field validation (e.g. confirm password) with pipe + forward + partialCheck?

[BittuChan]

Coming from Zod's .refine() / .superRefine(), I'm trying to validate that two fields match (classic confirm-password pattern) in Valibot. The docs mention forward and partialCheck, but it's not obvious how they compose together, especially when you also want to integrate with React Hook Form via @hookform/resolvers/valibot.

Specifically:

1. How do I validate that password and confirmPassword match and attach the error to the confirmPassword field?
2. Why use partialCheck instead of check here — what's the practical difference in a form context?
3. Does this work with valibotResolver from @hookform/resolvers out of the box, or do I need extra wiring?

[dosubot[bot]]

Hi @BittuChan! I'm Dosu and I’m helping the valibot team.

Here's the pattern for confirm password validation using pipe + forward + partialCheck:

import * as v from 'valibot';

const RegisterSchema = v.pipe(
  v.object({
    password: v.pipe(
      v.string(),
      v.minLength(8, 'Password must be at least 8 characters.')
    ),
    confirmPassword: v.string(),
  }),
  v.forward(
    v.partialCheck(
      [['password'], ['confirmPassword']],
      (input) => input.password === input.confirmPassword,
      'The two passwords do not match.'
    ),
    ['confirmPassword']
  )
);

How it works:

• partialCheck([['password'], ['confirmPassword']], ...) runs validation on those specific fields as soon as they're both valid
• forward(..., ['confirmPassword']) attaches the error to the confirmPassword field instead of the object level

Why partialCheck instead of check?

• check() only runs when the entire form is valid — so users wouldn't see the mismatch error until all other fields pass
• partialCheck() runs as soon as the selected fields are valid, giving better UX by showing the error immediately when both password fields are filled

React Hook Form integration:
It works with valibotResolver out of the box:

import { useForm } from 'react-hook-form';
import { valibotResolver } from '@hookform/resolvers/valibot';

const { register, formState: { errors } } = useForm({
  resolver: valibotResolver(RegisterSchema)
});
// Error appears at errors.confirmPassword thanks to forward()

Note: There was a TypeScript "Type instantiation is excessively deep" issue with this pattern that was fixed in v1.0.0-rc.4 — upgrade if you hit that.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[Shiven0504]

hey @BittuChan !

The key is that pipe wraps the whole object, not the individual fields because cross-field validation happens at the object level.

Minimal example:

import * as v from 'valibot';

const RegisterSchema = v.pipe(
  v.object({
    email: v.pipe(
      v.string(),
      v.nonEmpty('Email is required.'),
      v.email('Invalid email format.')
    ),
    password: v.pipe(
      v.string(),
      v.nonEmpty('Password is required.'),
      v.minLength(8, 'Must be at least 8 characters.')
    ),
    confirmPassword: v.string(),
  }),
  v.forward(
    v.partialCheck(
      [['password'], ['confirmPassword']],
      (input) => input.password === input.confirmPassword,
      'Passwords do not match.'
    ),
    ['confirmPassword']
  )
);

type RegisterData = v.InferOutput<typeof RegisterSchema>;

If you're using vue-tsc or strict tsc and get type errors on partialCheck paths, this was a known issue (#987). Make sure you're on the latest Valibot version, the path tuple inference was fixed.

[BittuChan]

Thanks @Shiven0504, this is working perfectly now.

The mental model shift from Zod was basically: Zod chains .refine() on the object and you pass a path option. Valibot separates the concern into two explicit pieces so partialCheck for the logic and forward for where the error goes. More verbose, but once you see the pattern it's straightforward, and the partial execution behavior is genuinely better for incremental form validation.

Each forward + partialCheck pair runs independently, so errors show up on the right fields without blocking each other. Hope this saves someone the hour I spent figuring it out.