Basic Usage

<van-form @submit="onSubmit">
  <van-cell-group inset>
    <van-field
      v-model="username"
      name="Username"
      label="Username"
      placeholder="Username"
      :rules="[{ required: true, message: 'Username is required' }]"
    />
    <van-field
      v-model="password"
      type="password"
      name="Password"
      label="Password"
      placeholder="Password"
      :rules="[{ required: true, message: 'Password is required' }]"
    />
  </van-cell-group>
  <div style="margin: 16px;">
    <van-button round block type="primary" native-type="submit">
      Submit
    </van-button>
  </div>
</van-form>

import { ref } from 'vue';

export default {
  setup() {
    const username = ref('');
    const password = ref('');
    const onSubmit = (values) => {
      console.log('submit', values);
    };

    return {
      username,
      password,
      onSubmit,
    };
  },
};

Validate Rules

<van-form @failed="onFailed">
  <van-cell-group inset>
    <van-field
      v-model="value1"
      name="pattern"
      placeholder="Use pattern"
      :rules="[{ pattern, message: 'Error message' }]"
    />
    <van-field
      v-model="value2"
      name="validator"
      placeholder="Use validator"
      :rules="[{ validator, message: 'Error message' }]"
    />
    <van-field
      v-model="value3"
      name="validatorMessage"
      placeholder="Use validator to return message"
      :rules="[{ validator: validatorMessage }]"
    />
    <van-field
      v-model="value4"
      name="asyncValidator"
      placeholder="Use async validator"
      :rules="[{ validator: asyncValidator, message: 'Error message' }]"
    />
  </van-cell-group>
  <div style="margin: 16px;">
    <van-button round block type="primary" native-type="submit">
      Submit
    </van-button>
  </div>
</van-form>

import { ref } from 'vue';
import { Toast } from 'vant';

export default {
  setup() {
    const value1 = ref('');
    const value2 = ref('');
    const value3 = ref('abc');
    const value4 = ref('');
    const pattern = /\\d{6}/;

    const validator = (val) => /1\\d{10}/.test(val);

    const validatorMessage = (val) => \`\${val} is invalid\`;

    const asyncValidator = (val) =>
      new Promise((resolve) => {
        Toast.loading('Validating...');

        setTimeout(() => {
          Toast.clear();
          resolve(val === '1234');
        }, 1000);
      });

    const onFailed = (errorInfo) => {
      console.log('failed', errorInfo);
    };

    return {
      value1,
      value2,
      value3,
      value4,
      pattern,
      onFailed,
      validator,
      asyncValidator,
      validatorMessage,
    };
  },
};

Field Type - Switch

<van-field name="switch" label="Switch">
  <template #input>
    <van-switch v-model="checked" size="20" />
  </template>
</van-field>

import { ref } from 'vue';

export default {
  setup() {
    const checked = ref(false);
    return { checked };
  },
};

Field Type - Checkbox

<van-field name="checkbox" label="Checkbox">
  <template #input>
    <van-checkbox v-model="checked" shape="square" />
  </template>
</van-field>
<van-field name="checkboxGroup" label="CheckboxGroup">
  <template #input>
    <van-checkbox-group v-model="groupChecked" direction="horizontal">
      <van-checkbox name="1" shape="square">Checkbox 1</van-checkbox>
      <van-checkbox name="2" shape="square">Checkbox 2</van-checkbox>
    </van-checkbox-group>
  </template>
</van-field>

import { ref } from 'vue';

export default {
  setup() {
    const checked = ref(false);
    const groupChecked = ref([]);
    return {
      checked,
      groupChecked,
    };
  },
};

Field Type - Radio

<van-field name="radio" label="Radio">
  <template #input>
    <van-radio-group v-model="checked" direction="horizontal">
      <van-radio name="1">Radio 1</van-radio>
      <van-radio name="2">Radio 2</van-radio>
    </van-radio-group>
  </template>
</van-field>

import { ref } from 'vue';

export default {
  setup() {
    const checked = ref('1');
    return { checked };
  },
};

Field Type - Stepper

<van-field name="stepper" label="Stepper">
  <template #input>
    <van-stepper v-model="value" />
  </template>
</van-field>

import { ref } from 'vue';

export default {
  setup() {
    const value = ref(1);
    return { value };
  },
};

Field Type - Rate

<van-field name="rate" label="Rate">
  <template #input>
    <van-rate v-model="value" />
  </template>
</van-field>

import { ref } from 'vue';

export default {
  setup() {
    const value = ref(3);
    return { value };
  },
};

Field Type - Slider

<van-field name="slider" label="Slider">
  <template #input>
    <van-slider v-model="value" />
  </template>
</van-field>

import { ref } from 'vue';

export default {
  setup() {
    const value = ref(50);
    return { value };
  },
};

Field Type - Uploader

<van-field name="uploader" label="Uploader">
  <template #input>
    <van-uploader v-model="value" />
  </template>
</van-field>

import { ref } from 'vue';

export default {
  setup() {
    const value = ref([
      { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' },
    ]);
    return { value };
  },
};

Field Type - Picker

<van-field
  v-model="result"
  is-link
  readonly
  name="picker"
  label="Picker"
  placeholder="Select city"
  @click="showPicker = true"
/>
<van-popup v-model:show="showPicker" position="bottom">
  <van-picker
    :columns="columns"
    @confirm="onConfirm"
    @cancel="showPicker = false"
  />
</van-popup>

import { ref } from 'vue';

export default {
  setup() {
    const result = ref('');
    const showPicker = ref(false);
    const columns = ['Delaware', 'Florida', 'Georqia', 'Indiana', 'Maine'];

    const onConfirm = (value) => {
      result.value = value;
      showPicker.value = false;
    };

    return {
      result,
      columns,
      onConfirm,
      showPicker,
    };
  },
};

Field Type - DatetimePicker

<van-field
  v-model="result"
  is-link
  readonly
  name="datetimePicker"
  label="Datetime Picker"
  placeholder="Select time"
  @click="showPicker = true"
/>
<van-popup v-model:show="showPicker" position="bottom">
  <van-datetime-picker
    type="time"
    @confirm="onConfirm"
    @cancel="showPicker = false"
  />
</van-popup>

import { ref } from 'vue';

export default {
  setup() {
    const result = ref('');
    const showPicker = ref(false);

    const onConfirm = (value) => {
      result.value = value;
      showPicker.value = false;
    };

    return {
      result,
      onConfirm,
      showPicker,
    };
  },
};

Field Type - Area

<van-field
  v-model="result"
  is-link
  readonly
  name="area"
  label="Area Picker"
  placeholder="Select area"
  @click="showArea = true"
/>
<van-popup v-model:show="showArea" position="bottom">
  <van-area
    :area-list="areaList"
    @confirm="onConfirm"
    @cancel="showArea = false"
  />
</van-popup>

import { ref } from 'vue';
import { areaList } from '@vant/area-data';

export default {
  setup() {
    const result = ref('');
    const showArea = ref(false);
    const onConfirm = (areaValues) => {
      showArea.value = false;
      result.value = areaValues
        .filter((item) => !!item)
        .map((item) => item.name)
        .join('/');
    };

    return {
      result,
      areaList,
      showArea,
      onConfirm,
    };
  },
};

Field Type - Calendar

<van-field
  v-model="result"
  is-link
  readonly
  name="calendar"
  label="Calendar"
  placeholder="Select date"
  @click="showCalendar = true"
/>
<van-calendar v-model:show="showCalendar" @confirm="onConfirm" />

import { ref } from 'vue';

export default {
  setup() {
    const result = ref('');
    const showCalendar = ref(false);
    const onConfirm = (date) => {
      result.value = \`\${date.getMonth() + 1}/\${date.getDate()}\`;
      showCalendar.value = false;
    };

    return {
      result,
      onConfirm,
      showCalendar,
    };
  },
};

API

Props

Attribute	Description	Type	Default
label-width	Field label width	number \| string	`6.2em`
label-align	Field label align, can be set to `center` `right`	string	`left`
input-align	Field input align, can be set to `center` `right`	string	`left`
error-message-align	Error message align, can be set to `center` `right`	string	`left`
validate-trigger	When to validate the form, can be set to `onChange`\u3001`onSubmit`, supports using array to set multiple values	string \| string[]	`onBlur`
colon	Whether to display colon after label	boolean	`false`
disabled	Whether to disable form	boolean	`false`
readonly	Whether to be readonly	boolean	`false`
validate-first	Whether to stop the validation when a rule fails	boolean	`false`
scroll-to-error	Whether to scroll to the error field when validation failed	boolean	`false`
show-error	Whether to highlight input when validation failed	boolean	`false`
show-error-message	Whether to show error message when validation failed	boolean	`true`
submit-on-enter	Whether to submit form on enter	boolean	`true`

Data Structure of Rule

Key	Description	Type
required	Whether to be a required field, the value is not allowed to be empty (empty string, empty array, `false`, `undefined`, `null`)	boolean
message	Error message, can be a function to dynamically return message content	string \| (value, rule) => string
validator	Custom validator, can return a Promise to validate dynamically	(value, rule) => boolean \| string \| Promise
pattern	Regexp pattern, if the regexp cannot match, means that the validation fails	RegExp
trigger	When to validate the form, priority is higher than the `validate-trigger` of the Form component, can be set to `onChange`, `onBlur`, `onSubmit`	string \| string[]
formatter	Format value before validate	(value, rule) => any
validateEmpty `v3.6.0`	Controls whether the `validator` and `pattern` options to verify empty values, the default value is `true`, you can set to `false` to disable this behavior	boolean

validate-trigger

Value	Description
onSubmit	Trigger validation after submitting form
onBlur	Trigger validation after submitting form or blurring input
onChange	Trigger validation after submitting form or changing input value

Events

Event	Description	Arguments
submit	Emitted after submitting the form and validation passed	values: object
failed	Emitted after submitting the form and validation failed	errorInfo: { values: object, errors: object[] }

Methods

Use ref to get Form instance and call instance methods.

Name	Description	Attribute	Return value
submit	Submit form	-	-
getValues `v3.4.8`	Get current form values	-	Record<string, unknown>
validate	Validate form	name?: string \| string[]	Promise<void>
resetValidation	Reset validation	name?: string \| string[]	-
getValidationStatus `v3.5.0`	Get validation status of all fields\uFF0Cstatus can be `passed`\u3001`failed`\u3001`unvalidated`	-	Record<string, FieldValidationStatus>
scrollToField	Scroll to field	name: string, alignToTop: boolean	-

Types

The component exports the following type definitions:

import type { FormProps, FormInstance } from 'vant';

FormInstance is the type of component instance:

import { ref } from 'vue';
import type { FormInstance } from 'vant';

const formRef = ref<FormInstance>();

formRef.value?.submit();

Form

Intro

Install

Usage

Basic Usage

Validate Rules

Field Type - Switch

Field Type - Checkbox

Field Type - Radio

Field Type - Stepper

Field Type - Rate

Field Type - Slider

Field Type - Uploader

Field Type - Picker

Field Type - DatetimePicker

Field Type - Area

Field Type - Calendar

API

Props

Data Structure of Rule

validate-trigger

Events

Methods

Types

Slots