Is there a way to validate default values on initial render (before mount)?

[akkadaska]

Hi, thank you for the great library!

Currently, we can specify validation strategies such as onMount, onChange, onBlur, and onSubmit. However, there doesn't seem to be a way to validate fields on the initial render, i.e., before the component is mounted.

This means that if default values are invalid, there's no way to show validation errors immediately without causing a flicker or layout shift. Using onMount does trigger validation, but it happens only after hydration, which can lead to a visible transition from "no error" to "error".

Is there a recommended way to validate default values during the initial render so that errors are already present in the server-rendered HTML? Or would it make sense to support an explicit onInit validation strategy for this purpose?

Thanks!

[LeCarbonator]

As of version 1.11, you can set field errors from formApi.setErrorMap. See the documentation for setting field-level errors from the form

const form = useForm({
 // ...
})

form.setErrorMap({
   onMount: {
      form: 'Mount errors set directly',
      fields: {
        'nested.field.error': 'An error'
      }
   }
})

If your validators are standard schemas, there is a helper function to help you format it:

const schema = z.object({ /* ... */ });

const form = useForm({
 // ...
});

form.setErrorMap({
  onMount: form.parseValuesWithSchema(schema)
})

[akkadaska]

Thanks so much — that makes sense!

I wasn't aware of parseValuesWithSchema, and it looks like that will work perfectly for my use case.

That said, I believe I still need to ensure this runs only once on initial render, perhaps using a ref or similar mechanism. For that reason, I still think it would be nice if there were a built-in validation phase like onInit that runs before mount automatically.

Anyway, my issue is resolved — thanks again for the clear explanation!

[LeCarbonator]

Thanks so much — that makes sense!

I wasn't aware of parseValuesWithSchema, and it looks like that will work perfectly for my use case.

That said, I believe I still need to ensure this runs only once on initial render, perhaps using a ref or similar mechanism. For that reason, I still think it would be nice if there were a built-in validation phase like onInit that runs before mount automatically.

Anyway, my issue is resolved — thanks again for the clear explanation!

OnMount manages state mounting as well, so I'm not sure how well a phase before that would be compatible. I'll keep it in mind!

[akkadaska]

Thanks, I see what you mean.

Just to clarify — the reason I'm asking about a phase before onMount is specifically for SSR. Since onMount doesn't run during server rendering, any onMount validations are skipped and only applied after hydration, which causes a mismatch and flicker.

With setErrorMap I can now manually inject those errors early on, which solves my issue — but I was originally thinking it might be nice if that behavior were automatic in SSR scenarios.

Thanks again for considering it!

[akkadaska]

@LeCarbonator

I tried the approach you suggested, but it doesn’t seem to work as expected.

Here’s a minimal reproduction: https://codesandbox.io/p/devbox/mtz7cq

This is a simple form built with Next.js, where both the first name and last name are required to be at least one character long. However, the initial values are empty strings. When the page is first loaded, there are no validation errors, but after a brief moment, the errors appear, causing a noticeable flicker.

The reason appears to be that even with the suggested approach, validation is still being triggered after mount — not during SSR or hydration. In fact, setErrorMap seems to be batched and applied later:

form/packages/form-core/src/FormApi.ts

Line 2188 in e5d6f9f

batch(() => {

As it stands, when using TanStack Form with SSR-enabled frameworks like Next.js, and when trying to display validation results immediately on load, this issue causes inevitable flickering. This can lead to layout shifts and negatively impact the overall user experience.

I hope there can be a solution to support proper validation during the initial SSR render.