Skip to content
ReferenceVersion 6.0.2

RForm and useForm ​

RForm wraps Naive UI Form and uses a spinner for submission or loading. Match NFormItem.path to the model field and update the value from the input.

tsx
import { RForm, useForm } from '@/components'
import { NButton, NFormItem, NInput } from 'naive-ui'
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    const [register, form] = useForm(
      { name: '' },
      {
        name: {
          key: 'name',
          required: true,
          message: 'Enter a name',
          trigger: 'blur',
        },
      },
    )
    const rules = form.formRules()
    const submit = async () => {
      await form.validate()
      console.log(form.formConditionRef.value.name)
    }
    return () => (
      <RForm
        onRegister={register}
        model={form.formConditionRef.value}
        rules={rules}
      >
        <NFormItem label="Name" path="name">
          <NInput
            value={form.formConditionRef.value.name}
            onUpdateValue={(name) => form.updateFormCondition({ name })}
          />
        </NFormItem>
        <NButton onClick={() => void submit().catch(() => {})}>
          Validate and submit
        </NButton>
        <NButton onClick={() => form.reset()}>Reset</NButton>
      </RForm>
    )
  },
})

Interactive example ​

View example source
tsx
import { useI18n } from '@/hooks'
import { RForm, useForm } from '@ray-template/ui/form'
import {
  NButton,
  NCard,
  NDatePicker,
  NFlex,
  NFormItemGi,
  NGrid,
  NInput,
  NInputNumber,
  NRadio,
  NRadioGroup,
} from 'naive-ui'
import DemoPage from '../components/DemoPage'
import DemoResult from '../components/DemoResult'

interface FormModel {
  name: string | null
  age: number | null
  gender: string | null
  date: number | null
  remark: string | null
}

export default defineComponent({
  name: 'RFormDemo',
  setup() {
    const { t } = useI18n('demoDetails')
    const rules = computed(() => ({
      name: {
        required: true,
        message: t('form.nameRequired'),
        trigger: ['blur', 'change'],
        key: 'name',
      },
      age: {
        required: true,
        message: t('form.ageRequired'),
        trigger: ['blur', 'change'],
        type: 'number' as const,
        min: 0,
        max: 120,
      },
      date: {
        required: true,
        message: t('form.dateRequired'),
        trigger: ['blur', 'change'],
        type: 'number' as const,
      },
      gender: {
        required: true,
        message: t('form.genderRequired'),
        trigger: 'change',
      },
    }))
    const [
      register,
      {
        validate,
        restoreValidation,
        validateTargetField,
        reset,
        formConditionRef: model,
      },
    ] = useForm<FormModel>({
      name: null,
      age: null,
      gender: null,
      date: null,
      remark: null,
    })
    const ids = { name: useId(), age: useId(), remark: useId() }
    const submission = ref<string>()
    const status = ref('form.waiting')

    const finish = () => {
      submission.value = JSON.stringify(model.value, null, 2)
      status.value = 'form.submitted'
    }

    const submit = async (event: Event) => {
      event.preventDefault()

      try {
        await validate()
        finish()
      } catch {
        submission.value = void 0
        status.value = 'form.invalid'
      }
    }

    return () => (
      <DemoPage title={t('form.title')} description={t('form.intro')}>
        <div class="r-demo-grid">
          <NCard title={t('form.profile')}>
            <RForm
              model={model.value}
              rules={rules.value}
              onRegister={register}
              onSubmit={submit}
              submitWhenEnter
              onFinish={finish}
            >
              <NGrid cols="1 480:2" responsive="self" xGap={16}>
                <NFormItemGi
                  label={t('form.name')}
                  labelProps={{ for: ids.name }}
                  path="name"
                >
                  <NInput
                    v-model:value={model.value.name}
                    inputProps={{ id: ids.name }}
                  />
                </NFormItemGi>
                <NFormItemGi
                  label={t('form.age')}
                  labelProps={{ for: ids.age }}
                  path="age"
                >
                  <NInputNumber
                    v-model:value={model.value.age}
                    inputProps={{ id: ids.age }}
                    min={0}
                    max={120}
                  />
                </NFormItemGi>
                <NFormItemGi label={t('form.date')} path="date">
                  <NDatePicker v-model:value={model.value.date} type="date" />
                </NFormItemGi>
                <NFormItemGi label={t('form.gender')} path="gender">
                  <NRadioGroup
                    v-model:value={model.value.gender}
                    aria-label={t('form.gender')}
                  >
                    <NRadio value="female">{t('form.female')}</NRadio>
                    <NRadio value="male">{t('form.male')}</NRadio>
                  </NRadioGroup>
                </NFormItemGi>
                <NFormItemGi
                  label={t('form.notes')}
                  labelProps={{ for: ids.remark }}
                  span={2}
                >
                  <NInput
                    type="textarea"
                    v-model:value={model.value.remark}
                    inputProps={{ id: ids.remark }}
                  />
                </NFormItemGi>
              </NGrid>
              <NFlex>
                <NButton type="primary" attrType="submit">
                  {t('form.submit')}
                </NButton>
                <NButton
                  onClick={() => {
                    reset({
                      name: 'Ray',
                      age: 28,
                      gender: 'female',
                      date: new Date(1998, 6, 12).getTime(),
                      remark: null,
                    })
                    submission.value = void 0
                    status.value = 'form.waiting'
                  }}
                >
                  {t('form.sample')}
                </NButton>
                <NButton
                  onClick={() => {
                    void validateTargetField('name')
                      .then(() => {
                        status.value = 'form.nameValid'
                      })
                      .catch(() => {
                        status.value = 'form.nameRequired'
                      })
                  }}
                >
                  {t('form.validateName')}
                </NButton>
                <NButton
                  onClick={() => {
                    restoreValidation()
                    status.value = 'form.waiting'
                  }}
                >
                  {t('form.clear')}
                </NButton>
                <NButton
                  onClick={() => {
                    reset()
                    submission.value = void 0
                    status.value = 'form.waiting'
                  }}
                >
                  {t('form.reset')}
                </NButton>
              </NFlex>
            </RForm>
          </NCard>
          <NCard title={t('form.payload')}>
            <DemoResult
              label={t(status.value)}
              error={status.value === 'form.invalid'}
            >
              <pre>{submission.value ?? t('empty')}</pre>
            </DemoResult>
          </NCard>
        </div>
      </DemoPage>
    )
  },
})

Props and events ​

The component inherits public NForm props and onSubmit and forwards the default slot to NForm.

PropDefaultDescription
loadingfalseCaller-controlled outer spinner.
loadingDescriptionNoneLoading description.
autocomplete'off'Written to the form element on mount.
submitWhenEnterfalseCan be enabled dynamically for single-line input. Successful validation calls onFinish. Repeated submissions are ignored while loading or while a prior submission is pending.
onFinishNoneCalled after Enter-triggered validation succeeds. Custom submit buttons should call validate() and perform the submission.
onRegister(inst)NoneProvides the Naive UI Form instance after mount. Accepts a callback or array.

Enter keeps its native behavior for IME confirmation, multiline input, comboboxes, buttons, modifier keys, and controls that already called preventDefault(). The form displays validation failures from keyboard submission. Vue error handling receives exceptions from onFinish. Handle rejected useForm.validate() promises. Access Form instance methods through the registration hook.

useForm ​

useForm(model?, rules?) returns [register, actions]. Bind register to onRegister. Initial values and rules can be objects or factories. Objects are deep-cloned. Factory results are used directly, so return a new object each time.

Return valueBehavior
formConditionRefReactive model for RForm.model and input bindings.
formModel() / formRules()Get fresh initial model and rules.
getFormInstance()Get the registered instance. Throws before registration or after unmount.
validate(callback?, shouldRuleBeApplied?)Forwards Naive UI validation. Handle rejection on failure.
validateTargetField(key)Selects rules by their unique key, which can differ from NFormItem.path.
restoreValidation()Clears validation and retains input.
updateFormCondition(values)Shallow-merges the current model and keeps initial values.
reset(values?)Merges initial values with overrides and clears validation. Dynamically added fields remain.

Call instance methods after the form mounts and registers. Declare nullable fields in the initial model and use an empty value appropriate for each input. When updating nested fields, account for the shallow merge.

Component source · useForm source · Form example