vant/src/field/README.md

Field

Install

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

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

Usage

Basic Usage

The value of field is bound with v-model.

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

export default {
  data() {
    return {
      value: '',
    };
  },
};

Custom Type

Use type prop to custom different type fields.

<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" />

export default {
  data() {
    return {
      tel: '',
      text: '',
      digit: '',
      number: '',
      password: '',
    };
  },
};

Disabled

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

Show Icon

<van-cell-group>
  <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>

export default {
  data() {
    return {
      value1: '',
      value2: '123',
    };
  },
};

Error Info

Use error or error-message to show error info.

<van-cell-group>
  <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-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>

Format Value

Use formatter prop to format the input value.

<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"
/>

export default {
  data() {
    return {
      value1: '',
      value2: '',
    };
  },
  methods: {
    formatter(value) {
      return value.replace(/\d/g, '');
    },
  },
};

Auto Resize

Textarea Field can be auto resize when has autosize prop.

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

Show Word Limit

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

Input Align

Use input-align prop to align the input value.

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

API

Props

Attribute	Description	Type	Default
v-model	Field value	number | string	-
label	Field label	string	-
name v2.5.0	Name	string	-
type	Input type, can be set to tel digit number textarea password	string	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 v2.7.2	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-trigger v2.9.1	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	string	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 show error info	boolean	false
error-message	Error message	string	-
formatter v2.4.2	Input value formatter	Function	-
format-trigger v2.8.7	When to format value，can be set to onBlur	string	onChange
arrow-direction	Can be set to left up down	string	right
label-class	Label className	any	-
label-width	Label width	number | string	6.2em
label-align	Label align, can be set to center right	string	left
input-align	Input align, can be set to center right	string	left
error-message-align	Error message align, can be set to center right	string	left
autosize	Textarea auto resize，can accpet an object, e.g. { maxHeight: 100, minHeight: 50 }	boolean | object	false
left-icon	Left side icon name	string	-
right-icon	Right side icon name	string	-
icon-prefix v2.5.3	Icon className prefix	string	van-icon
rules v2.5.0	Form validation rules	Rule[]	-

Events

Field support all native events of input tag

Event	Description	Parameters
input	Emitted when input value changed	value: string
focus	Emitted when input is focused	event: Event
blur	Emitted when input is blured	event: Event
clear	Emitted when the clear icon is clicked	event: Event
click	Emitted when component is clicked	event: Event
click-input v2.8.1	Emitted when the input is clicked	event: Event
click-left-icon	Emitted when the left icon is clicked	event: Event
click-right-icon	Emitted when the right icon is clicked	event: Event

Methods

Use ref to get Field instance and call instance methods.

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

Slots

Name	Description
label	Custom label
input	Custom input
left-icon	Custom left icon
right-icon	Custom right icon
button	Insert button
extra v2.8.2	Custom content on the right

Less Variables

How to use: Custom Theme.

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