React Hook Form: Why onChange Mode Still Validates on Blur and Delays Submit

I have a form where new users create a username.

I want to check username availability in real time using an asynchronous debounced validator. I configured React Hook Form with the mode set to 'onChange' to display availability feedback as the user types. However, I noticed two issues:

1. The form still revalidates on blur, even with 'onChange' mode.
2. On the first submit attempt, the form seems to trigger only the onBlur event (likely waiting for pending async validation) and does not submit until the second click.

This is my current implementation:

TYPESCRIPTCopied
const createDebouncedValidator = () => {
  let currentPromise: Promise<boolean> | null = null
  const debouncedCheck = debounce((username: string, resolve: (value: boolean) => void) => {
    checkAvailability('name', username)
      .then(({ available }) => resolve(available))
      .catch(() => resolve(false))
  }, 500)

  return async (username: string) => {
    if (username.length < 3) return true

    currentPromise = new Promise<boolean>(resolve => {
      debouncedCheck(username, resolve)
    })
    const result = await currentPromise
    currentPromise = null
    return result
  }
}

const onboardingFormSchema = z.object({
  username: z
    .string()
    .min(3, {
      message: 'Username must be at least 3 characters.',
    })
    .max(30, {
      message: 'Username must not be longer than 30 characters.',
    })
    .regex(/^[a-z0-9-]+$/, {
      message: 'Username can only contain lowercase letters, numbers, and hyphens.',
    })
    .refine(name => !name.startsWith('-') && !name.endsWith('-'), {
      message: 'Username cannot start or end with a hyphen.',
    })
    .refine(createDebouncedValidator(), { 
      message: 'This username is already taken' 
    })
})

type OnboardingFormValues = z.infer<typeof onboardingFormSchema>

export function OnboardingForm() {
  const { t } = useTranslations()
  const router = useRouter()
  const { setUser } = useAuth()
  const { finishOnboarding } = useOnboarding()

  const form = useForm<OnboardingFormValues>({
    resolver: zodResolver(onboardingFormSchema),
    defaultValues: {
      username: '',
    },
    mode: 'onChange',
  })

  const watchUsername = form.watch('username')

  async function onSubmit(data: OnboardingFormValues) {
    try {
      // Update username
      const updatedUser = await updateUsername(data.username)
      
      // Update global user state
      setUser(updatedUser)
      
      toast({
        title: t('settings.profile.updated'),
        description: t('settings.profile.usernameUpdated')
      })

      // Finish onboarding and redirect
      finishOnboarding()
      router.push('/links')
    } catch (error) {
      console.error('Profile update error:', error)
      toast({
        variant: 'destructive',
        title: t('common.error'),
        description: t('settings.profile.updateError')
      })
    }
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className='space-y-8'>
        <FormField
          control={form.control}
          name='username'
          render={({ field }) => (
            <FormItem>
              <FormLabel>Username</FormLabel>
              <FormControl>
                <div className="relative">
                  <Input 
                    {...field}
                    placeholder='username'
                    autoComplete='off'
                    autoCapitalize='off'
                  />
                  {form.formState.isValidating && (
                    <div className="absolute right-3 top-1/2 -translate-y-1/2">
                      <IconLoader2 className="h-4 w-4 animate-spin text-muted-foreground" />
                    </div>
                  )}
                </div>
              </FormControl>
              <FormDescription className="space-y-2">
                <p className="font-mono">
                  palmlink.eu/
                  <span className={cn(
                    watchUsername ? 'text-foreground' : 'text-muted-foreground',
                    'transition-colors'
                  )}>
                    {watchUsername || 'username'}
                  </span>
                </p>
                <ul className="text-xs list-disc list-inside space-y-1">
                  <li>Must be between 3 and 30 characters</li>
                  <li>Can only contain lowercase letters, numbers, and hyphens</li>
                  <li>Cannot start or end with a hyphen</li>
                </ul>
              </FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />
        <Button 
          type='submit' 
          className='w-full'
          disabled={!form.formState.isValid || form.formState.isValidating || form.formState.isSubmitting}
        >
          {form.formState.isSubmitting ? t('common.saving') : 'Continue'}
        </Button>
      </form>
    </Form>
  )
} 

I would appreciate suggestions on controlling validation triggers (like specifying reValidateMode) or restructuring the async validation so that it doesn’t interfere with form submission. My goal is to provide real-time username availability feedback without causing delayed or partial form submission.