N Form

n-form Component

The n-form component is the primary element for collecting and validating user input data in Naive UI applications. It works in conjunction with n-form-item to create structured, validated forms.

When to Use

Use n-form when you need to:

• Data Collection: Gather structured user input through various form controls
• Form Validation: Apply validation rules with automatic error display
• Form Submission: Handle form submission with validation checks
• Dynamic Forms: Create forms that can add or remove fields dynamically
• Complex Layouts: Build forms with flexible label placements and grid layouts

Basic Usage

Inline Form

An inline form displays form items horizontally in a single row.

<template>
  <n-form
    ref="formRef"
    inline
    :label-width="80"
    :model="formValue"
    :rules="rules"
  >
    <n-form-item label="Name" path="user.name">
      <n-input v-model:value="formValue.user.name" placeholder="Input Name" />
    </n-form-item>
    <n-form-item label="Age" path="user.age">
      <n-input v-model:value="formValue.user.age" placeholder="Input Age" />
    </n-form-item>
    <n-form-item>
      <n-button @click="handleValidateClick">Validate</n-button>
    </n-form-item>
  </n-form>
</template>

<script setup>
import { ref } from 'vue'

const formRef = ref(null)
const formValue = ref({
  user: {
    name: '',
    age: ''
  }
})

const rules = {
  user: {
    name: {
      required: true,
      message: 'Please input name',
      trigger: 'blur'
    },
    age: {
      required: true,
      message: 'Please input age',
      trigger: 'blur'
    }
  }
}

const handleValidateClick = () => {
  formRef.value?.validate((errors) => {
    if (!errors) {
      console.log('Validation passed')
    } else {
      console.log('Validation failed', errors)
    }
  })
}
</script>

Form with Validation

A standard form with comprehensive validation rules.

<template>
  <n-form ref="formRef" :model="modelRef" :rules="rules">
    <n-form-item path="age" label="Age">
      <n-input v-model:value="modelRef.age" @keydown.enter.prevent />
    </n-form-item>
    <n-form-item path="password" label="Password">
      <n-input
        v-model:value="modelRef.password"
        type="password"
        @input="handlePasswordInput"
        @keydown.enter.prevent
      />
    </n-form-item>
    <n-form-item
      ref="rPasswordFormItemRef"
      first
      path="reenteredPassword"
      label="Re-enter Password"
    >
      <n-input
        v-model:value="modelRef.reenteredPassword"
        :disabled="!modelRef.password"
        type="password"
        @keydown.enter.prevent
      />
    </n-form-item>
    <n-form-item>
      <n-button type="primary" @click="handleValidateButtonClick">
        Validate
      </n-button>
    </n-form-item>
  </n-form>
</template>

<script setup>
import { ref } from 'vue'

const formRef = ref(null)
const rPasswordFormItemRef = ref(null)
const modelRef = ref({
  age: null,
  password: '',
  reenteredPassword: ''
})

const rules = {
  age: [
    {
      required: true,
      type: 'number',
      message: 'Please input age',
      trigger: 'blur'
    }
  ],
  password: [
    {
      required: true,
      message: 'Please input password',
      trigger: 'blur'
    }
  ],
  reenteredPassword: [
    {
      required: true,
      message: 'Please re-enter password',
      trigger: 'blur'
    },
    {
      validator: (rule, value) => {
        return value === modelRef.value.password
      },
      message: 'Password does not match',
      trigger: 'blur'
    }
  ]
}

const handlePasswordInput = () => {
  if (modelRef.value.reenteredPassword) {
    rPasswordFormItemRef.value?.validate({ trigger: 'password-input' })
  }
}

const handleValidateButtonClick = () => {
  formRef.value?.validate((errors) => {
    if (!errors) {
      console.log('Validation passed')
    }
  })
}
</script>

Label Placement Top with Grid

Use n-grid and n-form-item-gi for precise form layout control.

<template>
  <n-form
    ref="formRef"
    :model="model"
    :rules="rules"
    label-placement="top"
  >
    <n-grid :span="24" :x-gap="24">
      <n-form-item-gi :span="12" label="Input" path="inputValue">
        <n-input v-model:value="model.inputValue" placeholder="Input" />
      </n-form-item-gi>
      <n-form-item-gi :span="12" label="Select" path="selectValue">
        <n-select
          v-model:value="model.selectValue"
          placeholder="Select"
          :options="generalOptions"
        />
      </n-form-item-gi>
      <n-form-item-gi :span="12" label="Datetime" path="datetimeValue">
        <n-date-picker v-model:value="model.datetimeValue" type="datetime" />
      </n-form-item-gi>
      <n-gi :span="24">
        <n-button type="primary" @click="handleValidateButtonClick">
          Validate
        </n-button>
      </n-gi>
    </n-grid>
  </n-form>
</template>

API Reference

n-form Props

n-form-item Props

n-form-item-gi Props

Accepts all props from n-form-item and n-grid-item.

FormItemRule Type

Events

Slots

n-form Slots

n-form-item Slots

Methods

n-form Methods

n-form-item Methods

Common Patterns

Validation Rules Examples

const rules = {
  // Required field
  name: {
    required: true,
    message: 'Please input name',
    trigger: 'blur'
  },
  
  // Number type with range
  age: [
    { required: true, type: 'number', message: 'Please input age' },
    { type: 'number', min: 0, max: 150, message: 'Age must be between 0 and 150' }
  ],
  
  // Email validation
  email: {
    type: 'email',
    message: 'Please input valid email',
    trigger: 'blur'
  },
  
  // Custom validator
  password: {
    validator: (rule, value) => {
      return value.length >= 8
    },
    message: 'Password must be at least 8 characters',
    trigger: 'blur'
  },
  
  // Async validation
  username: {
    asyncValidator: async (rule, value) => {
      const exists = await checkUsernameExists(value)
      if (exists) {
        throw new Error('Username already exists')
      }
    },
    trigger: 'blur'
  },
  
  // Warning level validation
  score: {
    level: 'warning',
    validator: (rule, value) => value >= 60,
    message: 'Score is below passing grade',
    trigger: 'blur'
  }
}

Custom Validation

<template>
  <n-form-item
    label="Airports"
    :validation-status="inputValidationStatus"
    :feedback="inputFeedback"
  >
    <n-input v-model:value="inputValue" clearable />
  </n-form-item>
</template>

<script setup>
import { ref, computed } from 'vue'

const inputValue = ref('')

const inputValidationStatus = computed(() => {
  if (!inputValue.value) return undefined
  return inputValue.value.length < 3 ? 'error' : 'success'
})

const inputFeedback = computed(() => {
  if (!inputValue.value) return ''
  return inputValue.value.length < 3 ? 'Minimum 3 characters' : ''
})
</script>

Dynamic Form

<template>
  <n-form ref="formRef" :model="dynamicForm">
    <n-form-item
      v-for="(item, index) in dynamicForm.hobbies"
      :key="index"
      :label="`Hobby ${index + 1}`"
      :path="`hobbies[${index}].name`"
      :rule="{
        required: true,
        message: 'Please input hobby',
        trigger: 'blur'
      }"
    >
      <n-input v-model:value="item.name" />
      <n-button @click="removeHobby(index)">Remove</n-button>
    </n-form-item>
    
    <n-form-item>
      <n-button @click="addHobby">Add Hobby</n-button>
    </n-form-item>
  </n-form>
</template>

<script setup>
import { ref } from 'vue'

const dynamicForm = ref({
  hobbies: [{ name: '' }]
})

const addHobby = () => {
  dynamicForm.value.hobbies.push({ name: '' })
}

const removeHobby = (index) => {
  dynamicForm.value.hobbies.splice(index, 1)
}
</script>

Partial Validation

<template>
  <n-form ref="formRef" :model="model" :rules="rules">
    <n-form-item label="Field A" path="fieldA">
      <n-input v-model:value="model.fieldA" />
    </n-form-item>
    <n-form-item label="Field B" path="fieldB">
      <n-input v-model:value="model.fieldB" />
    </n-form-item>
    <n-button @click="validateFieldAOnly">Validate Field A Only</n-button>
  </n-form>
</template>

<script setup>
const validateFieldAOnly = () => {
  formRef.value?.validate(undefined, (rule) => {
    return rule.key === 'fieldA'
  })
}
</script>

Best Practices

1. Use Nested Paths for Complex Data

// Model structure
const model = {
  user: {
    profile: {
      name: '',
      email: ''
    }
  }
}

// Form item path
// <n-form-item path="user.profile.name">

2. Set Proper Triggers

const rules = {
  // Validate on blur for text inputs
  name: { required: true, trigger: 'blur' },
  
  // Validate on input for immediate feedback
  password: { required: true, trigger: ['input', 'blur'] },
  
  // Multiple triggers
  email: { type: 'email', trigger: ['input', 'blur'] }
}

3. Use first for Better UX

When a field has multiple validation rules, use first to show only the first error:

<n-form-item first path="password" label="Password">
  <n-input v-model:value="model.password" type="password" />
</n-form-item>

4. Number Type for Required Number Fields

const rules = {
  age: {
    required: true,
    type: 'number',  // Important for number validation
    message: 'Please input age'
  }
}

5. Reset Form Properly

const resetForm = () => {
  formRef.value?.restoreValidation()
  Object.assign(model, getDefaultModel())
}

6. Use Warning Level for Non-blocking Validations

const rules = {
  score: {
    level: 'warning',  // Won't block form submission
    validator: (rule, value) => value >= 60,
    message: 'Score is below passing grade'
  }
}

7. Leverage Grid for Complex Layouts

Use n-form-item-gi with n-grid for responsive, multi-column layouts:

<n-form label-placement="top">
  <n-grid :cols="24" :x-gap="24">
    <n-form-item-gi :span="12" label="First Name" path="firstName">
      <n-input v-model:value="model.firstName" />
    </n-form-item-gi>
    <n-form-item-gi :span="12" label="Last Name" path="lastName">
      <n-input v-model:value="model.lastName" />
    </n-form-item-gi>
  </n-grid>
</n-form>

8. Custom Validation Messages

<template>
  <n-form :model="form" :rules="rules" :validate-messages="customMessages">
    <!-- form items -->
  </n-form>
</template>

<script setup>
const customMessages = {
  required: 'This field is required',
  types: {
    email: 'Please enter a valid email address'
  }
}
</script>