Intro

Field component let users enter and edit text.

Install

import { createApp } from 'vue';
import { Field, CellGroup } from 'vant';

const app = createApp();
app.use(Field);
app.use(CellGroup);

Basic Usage

The value of field is bound with v-model.

<van-cell-group inset>
  <van-field v-model="value" label="Label" placeholder="Text" />
</van-cell-group>

import { ref } from 'vue';

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

Custom Type

Use type prop to custom different type fields.

<van-cell-group inset>
  <van-field v-model="text" label="Text" />
  <van-field v-model="tel" type="tel" label="Phone" />
  <van-field v-model="digit" type="digit" label="Digit" />
  <van-field v-model="number" type="number" label="Number" />
  <van-field v-model="password" type="password" label="Password" />
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const tel = ref('');
    const text = ref('');
    const digit = ref('');
    const number = ref('');
    const password = ref('');

    return { tel, text, digit, number, password };
  },
};

Disabled

<van-cell-group inset>
  <van-field label="Text" model-value="Input Readonly" readonly />
  <van-field label="Text" model-value="Input Disabled" disabled />
</van-cell-group>

Show Icon

<van-cell-group inset>
  <van-field
    v-model="value1"
    label="Text"
    left-icon="smile-o"
    right-icon="warning-o"
    placeholder="Show Icon"
  />
  <van-field
    v-model="value2"
    clearable
    label="Text"
    left-icon="music-o"
    placeholder="Show Clear Icon"
  />
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const value1 = ref('');
    const value2 = ref('123');
    return {
      value1,
      value2,
    };
  },
};

Error Info

Use error or error-message to show error info.

<van-cell-group inset>
  <van-field
    v-model="username"
    error
    required
    label="Username"
    placeholder="Username"
  />
  <van-field
    v-model="phone"
    required
    label="Phone"
    placeholder="Phone"
    error-message="Invalid phone"
  />
</van-cell-group>

Insert Button

Use button slot to insert button.

<van-cell-group inset>
  <van-field v-model="sms" center clearable label="SMS" placeholder="SMS">
    <template #button>
      <van-button size="small" type="primary">Send SMS</van-button>
    </template>
  </van-field>
</van-cell-group>

Format Value

Use formatter prop to format the input value.

<van-cell-group inset>
  <van-field
    v-model="value1"
    label="Text"
    :formatter="formatter"
    placeholder="Format On Change"
  />
  <van-field
    v-model="value2"
    label="Text"
    :formatter="formatter"
    format-trigger="onBlur"
    placeholder="Format On Blur"
  />
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const value1 = ref('');
    const value2 = ref('');
    const formatter = (value) => value.replace(/\\d/g, '');

    return {
      value1,
      value2,
      formatter,
    };
  },
};

Auto Resize

Textarea Field can be auto resize when has autosize prop.

<van-cell-group inset>
  <van-field
    v-model="message"
    label="Message"
    type="textarea"
    placeholder="Message"
    rows="1"
    autosize
  />
</van-cell-group>

Show Word Limit

<van-cell-group inset>
  <van-field
    v-model="message"
    rows="2"
    autosize
    label="Message"
    type="textarea"
    maxlength="50"
    placeholder="Message"
    show-word-limit
  />
</van-cell-group>

Input Align

Use input-align prop to align the input value.

<van-cell-group inset>
  <van-field
    v-model="value"
    label="Text"
    placeholder="Input Align Right"
    input-align="right"
  />
</van-cell-group>

Props

Attribute	Description	Type	Default
v-model	Input value	number \| string	-
label	Left side label	string	-
name	As the identifier when submitting the form	string	-
id `v3.2.2`	Input id, the for attribute of the label also will be set	string	`van-field-n-input`
type	Input type, support all native types and `digit` type	FieldType	`text`
size	Size, can be set to `large`	string	-
maxlength	Max length of value	number \| string	-
placeholder	Input placeholder	string	-
border	Whether to show inner border	boolean	`true`
disabled	Whether to disable field	boolean	`false`
readonly	Whether to be readonly	boolean	`false`
colon	Whether to display colon after label	boolean	`false`
required	Whether to show required mark	boolean	`false`
center	Whether to center content vertically	boolean	`true`
clearable	Whether to be clearable	boolean	`false`
clear-icon `v3.0.12`	Clear icon name	string	`clear`
clear-trigger	When to display the clear icon, `always` means to display the icon when value is not empty, `focus` means to display the icon when input is focused	FieldClearTrigger	`focus`
clickable	Whether to show click feedback when clicked	boolean	`false`
is-link	Whether to show link icon	boolean	`false`
autofocus	Whether to auto focus, unsupported in iOS	boolean	`false`
show-word-limit	Whether to show word limit, need to set the `maxlength` prop	boolean	`false`
error	Whether to mark the input content in red	boolean	`false`
error-message	Error message	string	-
error-message-align	Error message align, can be set to `center` `right`	FieldTextAlign	`left`
formatter	Input value formatter	(val: string) => string	-
format-trigger	When to format value, can be set to `onBlur`	FieldFormatTrigger	`onChange`
arrow-direction	Can be set to `left` `up` `down`	string	`right`
label-class	Label className	string \| Array \| object	-
label-width	Label width	number \| string	`6.2em`
label-align	Label align, can be set to `center` `right`	FieldTextAlign	`left`
input-align	Input align, can be set to `center` `right`	FieldTextAlign	`left`
autosize	Textarea auto resize, can accept an object, e.g. { maxHeight: 100, minHeight: 50 }	boolean \| FieldAutosizeConfig	`false`
left-icon	Left side icon name	string	-
right-icon	Right side icon name	string	-
icon-prefix	Icon className prefix	string	`van-icon`
rules	Form validation rules	FieldRule[]	-
autocomplete `v3.0.3`	HTML native attribute, see MDN - autocomplete	string	-
enterkeyhint `v3.4.8`	HTML native attribute, see MDN - enterkeyhint	string	-

Events

Event	Description	Arguments
update:model-value	Emitted when input value changed	value: string
focus	Emitted when input is focused	event: Event
blur	Emitted when input is blurred	event: Event
clear	Emitted when the clear icon is clicked	event: MouseEvent
click	Emitted when component is clicked	event: MouseEvent
click-input	Emitted when the input is clicked	event: MouseEvent
click-left-icon	Emitted when the left icon is clicked	event: MouseEvent
click-right-icon	Emitted when the right icon is clicked	event: MouseEvent
start-validate `v3.5.1`	Emitted when start validation	-
end-validate `v3.5.1`	Emitted when end validation	{ status: string }

Methods

Use ref to get Field instance and call instance methods.

Name	Description	Attribute	Return value
focus	Trigger input focus	-	-
blur	Trigger input blur	-	-

Types

The component exports the following type definitions:

import type {
  FieldType,
  FieldRule,
  FieldProps,
  FieldInstance,
  FieldTextAlign,
  FieldRuleMessage,
  FieldClearTrigger,
  FieldFormatTrigger,
  FieldRuleValidator,
  FiledRuleFormatter,
  FieldValidateError,
  FieldAutosizeConfig,
  FieldValidateTrigger,
  FieldValidationStatus,
} from 'vant';

FieldInstance is the type of component instance:

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

const fieldRef = ref<FieldInstance>();

fieldRef.value?.focus();

Slots

Name	Description	SlotProps
label	Custom label	-
input	Custom input	-
left-icon	Custom left icon	-
right-icon	Custom right icon	-
button	Insert button	-
error-message `v3.2.5`	Custom error message	{ message: string }
extra	Custom content on the right	-

CSS Variables

The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.

Name	Default Value	Description
--van-field-label-width	6.2em	-
--van-field-label-color	var(--van-gray-7)	-
--van-field-label-margin-right	var(--van-padding-sm)	-
--van-field-input-text-color	var(--van-text-color)	-
--van-field-input-error-text-color	var(--van-danger-color)	-
--van-field-input-disabled-text-color	var(--van-text-color-3)	-
--van-field-placeholder-text-color	var(--van-text-color-3)	-
--van-field-icon-size	16px	-
--van-field-clear-icon-size	16px	-
--van-field-clear-icon-color	var(--van-gray-5)	-
--van-field-right-icon-color	var(--van-gray-6)	-
--van-field-error-message-color	var(--van-danger-color)	-
--van-field-error-message-font-size	12px	-
--van-field-text-area-min-height	60px	-
--van-field-word-limit-color	var(--van-gray-7)	-
--van-field-word-limit-font-size	var(--van-font-size-sm)	-
--van-field-word-limit-line-height	16px	-
--van-field-disabled-text-color	var(--van-text-color-3)	-
--van-field-required-mark-color	var(--van-red)	-

Field