How to trigger initial validation in Field.Root?

[Vinayaka-Hebbar]

I need help understanding how to trigger initial validation for a field created with Field.Root.

In my form, the field is marked as required, but Field.Root does not validate on mount.
Because of this, the field does not show its error state until the user interacts with it.

What I need help with

• How can I trigger validation on mount for a Field.Root field?
• Is there an API or recommended pattern to manually call validation (like validate() or triggerValidation() )?
• What is the correct approach to show initial error UI for required fields?

Context

• Validation must run immediately when the component is rendered.
• Error state should be visible on initial load without user interaction.

[mj12albert]

• Validation must run immediately when the component is rendered

I don't think we would support this directly (e.g. as a validationMode) since it's not an ideal UX

Is there an API or recommended pattern to manually call validation (like validate() or triggerValidation() )

There currently isn't, but I agree that this could be useful for other use-cases, we could possibly add it with an actionsRef prop (example)

[mj12albert]

const formRef = React.useRef()

React.useEffect(() => {
  formRef.current?.requestSubmit();
}, [])

<Form ref={formRef} />

Tried this as a workaround but flushSync prevents it from working:

base-ui/packages/react/src/field/useField.ts

Lines 48 to 49 in b185aaf

	// Synchronously update the validity state so the submit event can be prevented.
	ReactDOM.flushSync(() => commit(nextValue));

[Vinayaka-Hebbar]

I was able to implement a workaround on my side with my custom FormStore and Form wrapper (built on top of react-hook-form).

FormStore.ts

import {
  createFormControl,
  DefaultValues,
  ErrorOption,
  FieldErrors,
  FieldPath,
  FieldPathValue,
  FieldValues,
  FormState,
  UseFormProps,
  UseFormReturn,
} from 'react-hook-form';

import { createSelector, ReactStore } from '@base-ui-components/utils/store';

export interface FormStoreState<TValues extends FieldValues = FieldValues> {
  formState: FormState<TValues>;
  values: TValues;
}

export type FormStoreOptions<TValues extends FieldValues = FieldValues> = UseFormProps<TValues>;

function createFormSelectors<TValues extends FieldValues>() {
  return {
    formState: createSelector((state: FormStoreState<TValues>) => state.formState),
    errors: createSelector((state: FormStoreState<TValues>) => state.formState.errors),
    values: createSelector((state: FormStoreState<TValues>) => state.values),
    isDirty: createSelector((state: FormStoreState<TValues>) => state.formState.isDirty),
    isValid: createSelector((state: FormStoreState<TValues>) => state.formState.isValid),
    isSubmitting: createSelector((state: FormStoreState<TValues>) => state.formState.isSubmitting),
    isValidating: createSelector((state: FormStoreState<TValues>) => state.formState.isValidating),
    submitCount: createSelector((state: FormStoreState<TValues>) => state.formState.submitCount),
    dirtyFields: createSelector((state: FormStoreState<TValues>) => state.formState.dirtyFields),
    touchedFields: createSelector((state: FormStoreState<TValues>) => state.formState.touchedFields),
    errorCount: createSelector(
      (state: FormStoreState<TValues>) => state.formState.errors != null && Object.keys(state.formState.errors).length
    ),
    hasErrors: createSelector(
      (state: FormStoreState<TValues>) =>
        state.formState.errors != null && Object.keys(state.formState.errors).length > 0
    ),
  };
}

function createFormState<TValues extends FieldValues>(
  initialState: Partial<FormState<TValues>> = {}
): FormState<TValues> {
  return {
    isDirty: false,
    isValidating: false,
    isLoading: false,
    isSubmitted: false,
    isSubmitting: false,
    isSubmitSuccessful: false,
    isValid: false,
    submitCount: 0,
    dirtyFields: {},
    touchedFields: {},
    validatingFields: {},
    errors: {},
    disabled: false,
    isReady: false,
    ...initialState,
  };
}

type Selectors<TValues extends FieldValues> = ReturnType<typeof createFormSelectors<TValues>>;

// Form store wrapper built on top of react-hook-form’s internal createFormControl API
// (see: https://github.com/react-hook-form/react-hook-form/blob/master/src/useForm.ts)
export class FormStore<TValues extends FieldValues = FieldValues> extends ReactStore<
  FormStoreState<TValues>,
  Record<string, never>,
  Selectors<TValues>
> {
  readonly form: Omit<UseFormReturn<TValues>, 'formState'>;

  _values?: TValues;

  constructor(options: FormStoreOptions<TValues> = {}) {
    super(
      {
        formState: createFormState(),
        values: {} as TValues,
      },
      {},
      createFormSelectors<TValues>()
    );

    const { formControl: _, ...rest } = createFormControl<TValues>(options);

    this.form = {
      ...rest,
    };

    this.form.control._proxyFormState.isValid = 'all';
    this.form.control._proxyFormState.isDirty = 'all';
    this._values = options.values;
  }

  updateFormState(updates: Partial<FormState<TValues>>): void {
    this.set('formState', {
      ...this.state.formState,
      ...updates,
    });
  }

  updateValues(updates: Partial<TValues>): void {
    this.set('values', {
      ...this.state.values,
      ...updates,
    });
  }

  updateValue<TFieldName extends FieldPath<TValues>>(
    field: TFieldName,
    value: FieldPathValue<TValues, TFieldName>
  ): void {
    this.set('values', {
      ...this.state.values,
      [field]: value,
    });
  }

  setFieldValue<TFieldName extends FieldPath<TValues>>(
    field: TFieldName,
    value: FieldPathValue<TValues, TFieldName>
  ): void {
    this.form.control._subjects.state.next({
      name: field,
      type: 'change',
      values: {
        ...this.state.values,
        [field]: value,
      },
    });
  }

  setFieldError<TFieldName extends FieldPath<TValues>>(field: TFieldName, error: ErrorOption): void {
    this.form.setError(field, error);
  }

  setValues(values: Partial<TValues>): void {
    (Object.keys(values) as Array<FieldPath<TValues>>).forEach((key) => {
      const value = values[key as keyof TValues];
      if (value !== undefined) {
        this.form.setValue(key, value);
      }
    });
  }

  setErrors(errors: FieldErrors<TValues>): void {
    this.form.control._setErrors(errors);
  }

  reset(values?: DefaultValues<TValues>): void {
    this.form.reset(values);
  }
}

Form.tsx

import React from 'react';
import { DefaultValues, FieldErrors, FieldValues, FormProvider } from 'react-hook-form';

import { Form as MuiForm } from '@base-ui-components/react/form';
import { useIsoLayoutEffect } from '@base-ui-components/utils/useIsoLayoutEffect';

import { cn } from '#utils';

import { FormStore, FormStoreOptions } from './store';

export interface FormProps<TValues extends FieldValues = FieldValues> extends React.ComponentPropsWithoutRef<'form'> {
  className?: string;
  children: React.ReactNode;
  defaultValues?: DefaultValues<TValues>;
  validateOnMount?: boolean;
  fluid?: boolean;
  store?: FormStore<TValues>;
  disabled?: boolean;
  onStoreInit?: (store: FormStore<TValues>) => void;
  onFormSubmit?: (formValues: TValues, eventDetails: MuiForm.SubmitEventDetails) => void;
}

export namespace Form {
  export type Props<TValues extends FieldValues = FieldValues> = FormProps<TValues>;
  export type SubmitEventDetails = MuiForm.SubmitEventDetails;
  export type Errors<TValues extends FieldValues = FieldValues> = FieldErrors<TValues>;
}

export function createStore<TValues extends FieldValues>(options: FormStoreOptions<TValues>): FormStore<TValues> {
  return new FormStore<TValues>({ mode: 'onTouched', delayError: 600, ...options });
}

function deepEqual(a: any, b: any): boolean {
  if (a === b) return true;
  if (a == null || b == null) return false;
  if (typeof a !== 'object' || typeof b !== 'object') return false;

  const keysA = Object.keys(a);
  const keysB = Object.keys(b);

  if (keysA.length !== keysB.length) return false;

  for (const key of keysA) {
    if (!keysB.includes(key)) return false;
    if (!deepEqual(a[key], b[key])) return false;
  }

  return true;
}

export function Form<FormValues extends FieldValues = FieldValues>(props: FormProps<FormValues>) {
  const {
    className,
    validateOnMount = true,
    fluid,
    store,
    defaultValues,
    disabled,
    children,
    onStoreInit,
    onFormSubmit,
    ...rest
  } = props;

  const [internalStore] = React.useState(() => store ?? createStore({ defaultValues }));

  const formState = internalStore.useState('formState');

  const { control, trigger, handleSubmit, ...formMethods } = internalStore.form;

  useIsoLayoutEffect(() => {
    const unsubscribe = control._subscribe({
      formState: control._proxyFormState,
      callback: (state) => {
        internalStore.updateFormState({ ...state });
      },
      reRenderRoot: true,
    });

    const { unsubscribe: valuesUnsubscribe } = control._subjects.state.subscribe({
      next: (state) => {
        if (state.type == 'change' && state.values) {
          internalStore._values = state.values;
          internalStore.updateValues(state.values);
        }
      },
    });

    control._formState.isReady = true;
    internalStore.updateFormState({ isReady: true });

    return () => {
      unsubscribe();
      valuesUnsubscribe();
    };
  }, [control, internalStore]);

  React.useEffect(() => {
    return internalStore.observe('values', (values) => {
      if (values && !deepEqual(values, internalStore._values)) {
        control._reset(values, {
          keepFieldsRef: true,
          ...control._options.resetOptions,
        });
        if (!control._options.resetOptions?.keepIsValid) {
          control._setValid();
        }
        internalStore._values = values;
        internalStore.updateFormState({ ...control._formState });
      } else {
        control._resetDefaultValues();
      }
    });
  }, [control, internalStore]);

  React.useEffect(() => {
    if (control._proxyFormState.isDirty) {
      const isDirty = control._getDirty();
      if (isDirty !== formState.isDirty) {
        control._subjects.state.next({
          isDirty,
        });
      }
    }
  }, [control, formState.isDirty]);

  React.useEffect(() => {
    if (!control._state.mount) {
      control._setValid();
      control._state.mount = true;
    }

    if (control._state.watch) {
      control._state.watch = false;
      control._subjects.state.next({ ...control._formState });
    }

    control._removeUnmounted();
  });

  React.useEffect(() => {
    if (!store && onStoreInit) {
      onStoreInit(internalStore);
    }
  }, [store, onStoreInit, internalStore]);

  React.useEffect(() => control._disableForm(disabled), [control, disabled]);

  React.useEffect(() => {
    if (validateOnMount) {
      trigger();
    }
  }, [trigger, validateOnMount]);

  const wrappedHandleSubmit = React.useCallback(
    (e: React.FormEvent<HTMLFormElement>) => {
      if (onFormSubmit) {
        handleSubmit((values) => {
          onFormSubmit(values, { reason: 'none', event: e.nativeEvent });
        })(e);
      }
    },
    [handleSubmit, onFormSubmit]
  );

  return (
    <FormProvider
      control={control}
      trigger={trigger}
      handleSubmit={handleSubmit}
      formState={formState}
      {...formMethods}>
      <MuiForm className={cn('form', { fluid }, className)} onSubmit={wrappedHandleSubmit} {...rest}>
        {children}
      </MuiForm>
    </FormProvider>
  );
}