Field - Vant 4
Field
📝 Create beautiful and interactive input fields that make data entry a breeze! Perfect for forms, search bars, and user interactions.
🌟 Intro
The Field component is your go-to solution for text input and editing! 🎯 Whether you need simple text fields, password inputs, or complex form validation, this versatile component handles it all with style and ease. ✨ From basic inputs to advanced features like auto-resize, formatting, and validation - Field makes user input smooth and delightful! 🚀
📦 Install
Get started with Field by registering it globally! 🎉 Use app.use() for global registration, or check out Component Registration for more flexible installation options.
import { createApp } from'vue'; import { Field, CellGroup } from'vant'; const app = createApp(); app.use(Field); app.use(CellGroup);🎨 Usage
✨ Basic Usage
Create your first input field with v-model binding! 🔗 The field value automatically syncs with your data, making form handling effortless and reactive.
import { ref } from'vue'; exportdefault { setup() { const value = ref(''); return { value }; }, };🎭 Custom Type
Transform your fields with different input types! 📱 From telephone numbers to passwords, each type provides specialized keyboard layouts and validation for the perfect user experience.
import { ref } from'vue'; exportdefault { setup() { const tel = ref(''); const text = ref(''); const digit = ref(''); const number = ref(''); const password = ref(''); return { tel, text, digit, number, password }; }, };🚫 Disabled
Create read-only fields that maintain visual consistency! 🔒 Perfect for displaying information that shouldn't be edited while keeping the form layout intact.
🎨 Show Icon
Add visual flair with icons! ✨ Use left and right icons to enhance usability and provide visual cues for different field types and actions.
import { ref } from'vue'; exportdefault { setup() { const value1 = ref(''); const value2 = ref('123'); return { value1, value2, }; }, };⭐ Required
Mark essential fields with a visual asterisk! 🌟 The required prop adds clear visual indicators to help users identify mandatory fields at a glance.
Please note that the required prop is only used for controlling the style. For form validation, you need to use the rule.required option to control the validation logic.
🤖 Auto Required
Smart form validation made easy! 🧠 Set required="auto" on the Form component and watch as all fields automatically display asterisks based on their validation rules - no manual configuration needed!
⚠️ Error Info
Provide clear feedback with error states! 🚨 Use error or error-message props to highlight validation issues and guide users toward correct input with helpful error messages.
🔘 Insert Button
Enhance your fields with action buttons! 💫 Use the button slot to add interactive elements like submit buttons, clear actions, or custom controls right within your input fields.
### 🎯 Format Value
Transform input on-the-fly with custom formatting! ✨ The `formatter` prop lets you automatically format user input - perfect for phone numbers, credit cards, or any custom format you need.
```htmlimport { ref } from'vue'; exportdefault { setup() { const value1 = ref(''); const value2 = ref(''); constformatter = (value) => value.replace(/\d/g, ''); return { value1, value2, formatter, }; }, };📏 Auto Resize
Smart textarea that grows with your content! 🌱 Enable autosize and watch your textarea automatically expand and contract based on the text length - no more scrolling in tiny boxes!
📊 Show Word Limit
Keep users informed with character counting! 📝 Display remaining characters to help users stay within limits and provide clear feedback about input length constraints.
🎯 Input Align
Perfect text alignment for every design! ✨ Use input-align to position your input text exactly where you want it - left, center, or right alignment for optimal visual harmony.
🏷️ Label Align
Flexible label positioning for any layout! 🎨 Control label alignment with label-align - choose from center, right, or top positioning to match your design perfectly.
🔧 API
Comprehensive configuration options to customize every aspect of your Field component! 🎛️ From basic props to advanced validation rules, everything you need is at your fingertips.
📋 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``normal | string | - | | maxlength | Max length of value | number | string | - | | min v4.9.5 | When the input type is number or digit, set the minimum allowable value | number | - | | max v4.9.5 | When the input type is number or digit, set the maximum allowable value | number | - | | 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 | 'auto' | null | | 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 | - | | autocapitalize v4.6.2 | HTML native attribute, see MDN - autocapitalize | string | - | | enterkeyhint | HTML native attribute, see MDN - enterkeyhint | string | - | | spellcheck v4.6.2 | HTML native attribute, see MDN - spellcheck | boolean | - | | autocorrect v4.6.2 | HTML native attribute, Safari only, see MDN - autocorrect | string | - |
| inputmode v4.9.9 | HTML native attribute, see MDN - inputmode | string | Set automatically according to the type prop |
🎪 Events
Listen to user interactions and field state changes! 🎯 From input changes to validation events, stay connected to every important moment in your field's lifecycle.
| 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
Programmatic control at your fingertips! 🎮 Use ref to access Field instance methods and control focus behavior dynamically.
| Name | Description | Attribute | Return value |
|---|---|---|---|
| focus | Trigger input focus | - | - |
| blur | Trigger input blur | - | - |
📝 Types
Full TypeScript support for type-safe development! 🛡️ Import comprehensive type definitions to ensure your Field implementation is robust and error-free.
importtype { 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'; importtype { FieldInstance } from'vant'; const fieldRef = ref<FieldInstance>(); fieldRef.value?.focus();🎨 Slots
Unlimited customization possibilities! ✨ Replace or enhance any part of your field with custom content using these flexible slot options.
| 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 | 18px | - |
| --van-field-clear-icon-size | 18px | - |
| --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) | - |
📚 Related Docs
- Form - Complete form validation and submission
- Button - Action buttons for forms
- Icon - Custom icons for field states
- ConfigProvider - Global configuration and theming
- Advanced Usage - Tips and best practices