docs/en-US/component/input.md
Input data using mouse or keyboard.
:::demo
input/basic
:::
:::demo Disable the Input with the disabled attribute.
input/disabled
:::
:::demo Make the Input clearable with the clearable attribute. After version ^(2.13.4), the clearable feature is also available for textarea type of Input.
input/clearable
:::
:::demo You can customize the clear icon by setting the clear-icon attribute.
input/clear-icon
:::
Display value within it's situation with formatter, and we usually use parser at the same time.
:::demo
input/formatter
:::
:::demo Make a toggle-able password Input with the show-password attribute. Since ^(2.13.6), the password-icon slot is supported to override the default icon.
input/password
:::
Add an icon to indicate input type.
:::demo To add icons in Input, you can simply use prefix-icon and suffix-icon attributes. Also, the prefix and suffix named slots works as well.
input/with-icon
:::
Resizable for entering multiple lines of text information. Add attribute type="textarea" to change input into native textarea.
:::demo Control the height by setting the rows prop.
input/textarea
:::
Setting the autosize prop for a textarea type of Input makes the height to automatically adjust based on the content. An options object can be provided to autosize to specify the minimum and maximum number of lines the textarea can automatically adjust.
:::demo
input/auto-sizing-textarea
:::
Prepend or append an element, generally a label or a button.
:::demo Use slot to distribute elements that prepend or append to Input.
input/mixed-input
:::
:::demo Add size attribute to change the size of Input. In addition to the default size, there are two other options: large, small.
input/various-size
:::
:::demo maxlength and minlength attributes of input, they declare a limit on the number of characters a user can input. The "number of characters" is measured using JavaScript string length.Setting the maxlength prop for a text or textarea type of Input can limit the length of input value, allows you to show word count by setting show-word-limit to true at the same time. In ^(2.11.5), You can set word-limit-position to outside to display the word count outside the input.
input/length-limiting
:::
:::demo Set count-graphemes to calculate text length. If it's set, native maxlength and minlength won't be used.
input/count-graphemes
:::
:::tip
Browser Support & Fallback Strategy
When using the count-graphemes prop, the component employs the following approach:
Primary: Uses Intl.Segmenter API (Chrome 87+, Firefox 125+, Safari 14.1+) for proper grapheme cluster handling. This correctly handles complex emoji, combining marks, and Zero Width Joiner sequences.
Fallback: Older browsers fall back to Array.from() for code-point based iteration. Note that this may split multi-codepoint grapheme sequences (e.g., emoji with skin tone modifiers).
When implementing your own count-graphemes function, consider using Intl.Segmenter if you need robust support for complex unicode characters.
:::
| Name | Description | Type | Default |
|---|---|---|---|
| type | type of input, see more in MDN | ^[string]'text' | 'textarea' | 'number' | 'password' | 'email' | 'search' | 'tel' | 'url' | text |
| model-value / v-model | binding value | ^[string] / ^[number] | — |
| model-modifiers ^(2.11.5) | v-model modifiers, reference Vue modifiers | ^[object]{ lazy?: true, number?: true, trim?: true } | — |
| maxlength | same as maxlength in native input | ^[string] / ^[number] | — |
| minlength | same as minlength in native input | ^[string] / ^[number] | — |
| show-word-limit | whether show word count, only works when type is 'text' or 'textarea' | ^[boolean] | false |
| word-limit-position ^(2.11.5) | word count position, valid when show-word-limit is true | ^[enum]'inside' | 'outside' | "inside" |
| placeholder | placeholder of Input | ^[string] | — |
| clearable | whether to show clear button, only works when type is not 'textarea' | ^[boolean] | false |
| clear-icon ^(2.11.0) | custom clear icon component | ^[string] / ^[object]Component | CircleClose |
| formatter | specifies the format of the value presented input.(only works when type is 'text') | ^[Function](value: string | number) => string | — |
| parser | specifies the value extracted from formatter input.(only works when type is 'text') | ^[Function](value: string) => string | — |
| show-password | whether to show toggleable password input | ^[boolean] | false |
| disabled | whether Input is disabled | ^[boolean] | false |
| size | size of Input, works when type is not 'textarea' | ^[enum]'large' | 'default' | 'small' | — |
| prefix-icon | prefix icon component | ^[string] / ^[Component] | — |
| suffix-icon | suffix icon component | ^[string] / ^[Component] | — |
| rows | number of rows of textarea, only works when type is 'textarea' | ^[number] | 2 |
| autosize | whether textarea has an adaptive height, only works when type is 'textarea'. Can accept an object, e.g. { minRows: 2, maxRows: 6 } | ^[boolean] / ^[object]{ minRows?: number, maxRows?: number } | false |
| autocomplete | same as autocomplete in native input | ^[string] | off |
| name | same as name in native input | ^[string] | — |
| readonly | same as readonly in native input | ^[boolean] | false |
| max | same as max in native input | — | — |
| min | same as min in native input | — | — |
| step | same as step in native input | — | — |
| resize | control the resizability | ^[enum]'none' | 'both' | 'horizontal' | 'vertical' | — |
| autofocus | same as autofocus in native input | ^[boolean] | false |
| form | same as form in native input | string | — |
| aria-label ^(a11y) ^(2.7.2) | same as aria-label in native input | ^[string] | — |
| tabindex | input tabindex | ^[string] / ^[number] | — |
| validate-event | whether to trigger form validation | ^[boolean] | true |
| input-style | the style of the input element or textarea element | ^[string] / ^[object]CSSProperties | CSSProperties[] | string[] | {} |
| label ^(a11y) ^(deprecated) | same as aria-label in native input | ^[string] | — |
| inputmode ^(2.10.3) | same as inputmode in native input | ^[string] | — |
| count-graphemes ^(2.13.7) | custom function to count graphemes; when set, native maxlength/minlength constraints are bypassed. Component uses Intl.Segmenter (Chrome 87+, Firefox 125+, Safari 14.1+) for proper grapheme clustering; older browsers fall back to Array.from() for code-point iteration | ^[Function](value: string) => number | — |
| Name | Description | Type |
|---|---|---|
| blur | triggers when Input blurs | ^[Function](event: FocusEvent) => void |
| focus | triggers when Input focuses | ^[Function](event: FocusEvent) => void |
| change | triggers when the input box loses focus or the user presses Enter, only if the modelValue has changed | ^[Function](value: string | number, evt?: Event) => void |
| input | triggers when the Input value change | ^[Function](value: string | number) => void |
| clear | triggers when the Input is cleared by clicking the clear button | ^[Function](evt?: MouseEvent) => void (After version 2.13.4, the evt parameter can be received) |
| keydown | triggers when a key is pressed down | ^[Function](event: KeyboardEvent | Event) => void |
| mouseleave | triggers when the mouse leaves the Input element | ^[Function](event: MouseEvent) => void |
| mouseenter | triggers when the mouse enters the Input element | ^[Function](event: MouseEvent) => void |
| compositionstart | triggers when the composition starts | ^[Function](event: CompositionEvent) => void |
| compositionupdate | triggers when the composition is updated | ^[Function](event: CompositionEvent) => void |
| compositionend | triggers when the composition ends | ^[Function](event: CompositionEvent) => void |
| Name | Description |
|---|---|
| prefix | content as Input prefix, only works when type is not 'textarea' |
| suffix | content as Input suffix, only works when type is not 'textarea' |
| prepend | content to prepend before Input, only works when type is not 'textarea' |
| append | content to append after Input, only works when type is not 'textarea' |
| password-icon ^(2.13.6) | content as Input password icon, only works when show-password is true. The scope variable is { visible: boolean } |
| Name | Description | Type |
|---|---|---|
| blur | blur the input element | ^[Function]() => void |
| clear | clear input value | ^[Function]() => void |
| focus | focus the input element | ^[Function]() => void |
| input | HTML input element | ^[object]Ref<HTMLInputElement> |
| ref | HTML element, input or textarea | ^[object]Ref<HTMLInputElement | HTMLTextAreaElement> |
| resizeTextarea | resize textarea | ^[Function]() => void |
| select | select the text in input element | ^[Function]() => void |
| textarea | HTML textarea element | ^[object]Ref<HTMLTextAreaElement> |
| textareaStyle | style of textarea | ^[object]Ref<StyleValue> |
| isComposing ^(2.8.0) | is input composing | ^[object]Ref<boolean> |
| passwordVisible ^(2.13.7) | whether the password is visible | ^[object]Ref<boolean> |
Typical issue: #7287
PS: Since the ElInput component does not have a default width, when the clearable icon is displayed, the width of the component will be expanded, which can be solved by setting width.
<el-input v-model="input" clearable style="width: 200px" />