vant/packages/vant/src/field

Field

Intro

Field component let users enter and edit text.

Install

Register component globally via app.use, refer to Component Registration for more registration ways.

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

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

Usage

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>

Label Align

Use label-align prop to align the input value.

<van-cell-group inset>
  <van-field
    v-model="value"
    label="Tel"
    placeholder="Please input tel number"
    label-align="top"
  />
</van-cell-group>

API

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	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	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 top	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	HTML native attribute, see MDN - autocomplete	string	-
enterkeyhint	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	Emitted when start validation	-
end-validate	Emitted when end validation	{ status: string, message: 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,
  FieldRuleFormatter,
  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	Custom error message	{ message: string }
extra	Custom content on the right	-

Theming

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-text-color)	-
--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)	-