React项目中NextUI Checkbox无法注册到react-hook-form的问题

问题根源 #

NextUI的组件（如Checkbox）并非原生HTML元素，内部封装了自定义状态管理与事件逻辑，直接传递react-hook-form的register返回props会出现兼容问题：

• register返回的是针对原生input的onChange、name等属性，但NextUI组件的事件触发方式、属性命名与原生不一致
• 这会导致表单字段无法被正确追踪，甚至抛出Cannot read properties of undefined (reading 'name')错误

解决方案 #

1. Checkbox组件：用Controller适配 #

react-hook-form提供的Controller组件专门用于对接第三方受控组件，通过它可以同步表单状态与NextUI组件状态：

import { useForm, Controller } from 'react-hook-form';
import { Checkbox, Text } from '@nextui-org/react';

export default function LoginForm() {
  const { control, handleSubmit } = useForm({
    defaultValues: {
      remember: false // 设置默认值，避免初始为undefined
    }
  });

  const onSubmitLogin = (data) => {
    console.log(data); // 此时remember会正确返回true/false
  };

  return (
    <form onSubmit={handleSubmit(onSubmitLogin)}>
      <Controller
        name="remember"
        control={control}
        render={({ field }) => (
          <Checkbox
            isSelected={field.value}
            onValueChange={field.onChange}
          >
            <Text size={14}>Remember me</Text>
          </Checkbox>
        )}
      />
      <button type="submit">登录</button>
    </form>
  );
}

2. NextUI输入框（Input组件）的两种注册方式 #

方式一：register + inputProps

NextUI的Input组件提供inputProps属性，用于传递原生input的props，直接将register返回值传入即可：

import { useForm } from 'react-hook-form';
import { Input } from '@nextui-org/react';

export default function LoginForm() {
  const { register, handleSubmit } = useForm({
    defaultValues: {
      email: '',
      password: ''
    }
  });

  const onSubmitLogin = (data) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmitLogin)}>
      <Input
        label="邮箱"
        placeholder="请输入邮箱"
        inputProps={register('email', { required: '邮箱不能为空' })}
      />
      <Input
        label="密码"
        placeholder="请输入密码"
        type="password"
        inputProps={register('password', { required: '密码不能为空' })}
      />
    </form>
  );
}

方式二：Controller包裹（适用于精细控制场景）

如果需要对输入框做自定义状态处理，也可以用Controller：

import { useForm, Controller } from 'react-hook-form';
import { Input } from '@nextui-org/react';

export default function LoginForm() {
  const { control, handleSubmit } = useForm({
    defaultValues: {
      email: ''
    }
  });

  const onSubmitLogin = (data) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmitLogin)}>
      <Controller
        name="email"
        control={control}
        rules={{ required: '邮箱不能为空' }}
        render={({ field }) => (
          <Input
            label="邮箱"
            placeholder="请输入邮箱"
            value={field.value}
            onChange={(e) => field.onChange(e.target.value)}
          />
        )}
      />
    </form>
  );
}

关键注意事项 #

• 始终为表单字段设置defaultValues，避免初始状态为undefined
• 对于NextUI自定义组件，优先使用Controller或组件提供的原生props传递入口（如Input的inputProps），而非直接传递register返回的props

内容的提问来源于stack exchange，提问作者LXT