Input

출처: 문서

본문

마우스나 키보드로 데이터를 입력할 때 사용하는 입력 컴포넌트예요. 폼에서 가장 기본적으로 쓰는 입력란이라고 보면 돼요.

기본 사용 (Basic usage)

v-model로 값을 바인딩해요.

비활성 (Disabled)

disabled 속성으로 Input을 비활성화할 수 있어요.

clearable (지우기 가능)

clearable 속성으로 Input을 지울 수 있게 만들 수 있어요. 2.13.4 버전 이후부터는 textarea 타입의 Input에서도 clearable 기능을 쓸 수 있어요.

<template>
  <div class="input-group">
    <el-input v-model="input" placeholder="Please input" clearable />
    <el-input v-model="textareaInput" type="textarea" placeholder="Please input" clearable />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const input = ref('')
const textareaInput = ref('')
</script>

.input-group {
  display: flex;
  align-items: center;
  gap: 1em;
}

커스텀 클리어 아이콘 (Custom Clear Icon) 2.11.0

clear-icon 속성을 설정해 클리어 아이콘을 커스터마이즈할 수 있어요.

<template>
  <div class="input-group">
    <el-input v-model="input" placeholder="Please input" clearable clear-icon="CloseBold" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { CloseBold } from '@element-plus/icons-vue'

const input = ref('Custom clear icon')
const textareaInput = ref('Custom clear icon')
</script>

.input-group {
  display: flex;
  flex-direction: column;
  gap: 1em;
}

Formatter

formatter로 상황에 맞는 표시 값을 보여주고, 보통 parser를 함께 사용해요. 형식화된 값은 parser로 다시 원래 값으로 풀어내요.

비밀번호 상자 (Password box)

show-password 속성으로 토글이 가능한 비밀번호 Input을 만들 수 있어요. 2.13.6부터는 password-icon 슬롯으로 기본 아이콘을 덮어쓸 수 있어요.

<template>
  <div class="input-group">
    <el-input v-model="input" type="password" placeholder="Please input password" show-password />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Lock, Unlock } from '@element-plus/icons-vue'

const input = ref('')
</script>

.input-group {
  display: flex;
  align-items: center;
  gap: 1em;
}

아이콘이 있는 Input (Input with icon)

입력 타입을 알려주는 아이콘을 추가할 수 있어요. Input에 아이콘을 추가하려면 간단히 prefix-icon과 suffix-icon 속성을 쓰면 돼요. prefix와 suffix라는 이름의 슬롯도 함께 동작해요.

<template>
  <div class="demo-input-with-icon">
    <div class="input-group">
      <span class="label">Using attributes</span>
      <div class="input-container">
        <el-input v-model="input1" class="responsive-input" placeholder="Type something" prefix-icon="Search" />
        <el-input v-model="input2" class="responsive-input" placeholder="Type something" suffix-icon="Calendar" />
      </div>
    </div>
    <div class="input-group">
      <span class="label">Using slots</span>
      <div class="input-container">
        <el-input v-model="input3" class="responsive-input" placeholder="Type something">
          <template #prefix>
            <el-icon><Search /></el-icon>
          </template>
        </el-input>
        <el-input v-model="input4" class="responsive-input" placeholder="Type something">
          <template #suffix>
            <el-icon><Calendar /></el-icon>
          </template>
        </el-input>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Calendar, Search } from '@element-plus/icons-vue'

const input1 = ref('')
const input2 = ref('')
const input3 = ref('')
const input4 = ref('')
</script>

.demo-input-with-icon {
  width: 100%;
}

.input-group {
  margin-bottom: 1.5rem;
}

.label {
  display: block;
  margin-bottom: 1rem;
  color: var(--el-text-color-regular);
}

.input-container {
  display: flex;
  gap: 1rem;
  flex-wrap: wrap;
}

.responsive-input {
  width: 240px;
}

@media (max-width: 768px) {
  .input-container {
    flex-direction: column;
    gap: 1rem;
  }

  .responsive-input {
    width: 100%;
  }
}

Textarea

여러 줄의 텍스트 정보를 입력할 수 있도록 크기를 조절할 수 있는 textarea예요. type="textarea" 속성을 추가하면 네이티브 textarea로 바뀌고, rows prop으로 높이를 제어할 수 있어요.

Autosize Textarea

textarea 타입의 Input에 autosize prop을 설정하면 내용에 따라 높이가 자동으로 조절돼요. 자동으로 조절될 줄 수의 최솟값과 최댓값을 지정하려면 autosize에 객체를 전달할 수도 있어요(예: { minRows: 2, maxRows: 6 }).

혼합 입력 (Mixed input)

보통 라벨이나 버튼인 요소를 앞(prepend)이나 뒤(append)에 붙일 수 있어요. 슬롯을 사용해 Input에 앞뒤로 붙일 요소를 배치할 수 있어요.

<template>
  <div>
    <el-input v-model="input1" placeholder="Please input" class="input-with-select">
      <template #prepend>Http://</template>
    </el-input>
    <el-input v-model="input2" placeholder="Please input" class="input-with-select">
      <template #append>.com</template>
    </el-input>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Search } from '@element-plus/icons-vue'

const input1 = ref('')
const input2 = ref('')
const input3 = ref('')
const select = ref('')
</script>

.input-with-select .el-input-group__prepend {
  background-color: var(--el-fill-color-blank);
}

크기 (Sizes)

size 속성을 추가해 Input의 크기를 바꿀 수 있어요. 기본 크기 외에 large와 small 두 가지 옵션이 더 있어요.

길이 제한 (Limit length)

input의 maxlength와 minlength 속성은 사용자가 입력할 수 있는 문자 수의 한도를 정해요. "문자 수"는 JavaScript string length로 측정돼요. text 또는 textarea 타입의 Input에 maxlength prop을 설정하면 입력값 길이를 제한할 수 있고, 동시에 show-word-limit를 true로 설정하면 글자 수를 보여줄 수 있어요. 2.11.5에서는 word-limit-position을 outside로 설정해 입력란 바깥에 글자 수를 표시할 수도 있어요.

Grapheme 세기 (Count graphemes) 2.13.7

count-graphemes를 설정하면 텍스트 길이를 계산해요. 이 값이 설정되면 네이티브 maxlength와 minlength는 사용되지 않아요.

TIP

브라우저 지원 및 폴백 전략

count-graphemes prop을 사용할 때 컴포넌트는 다음 방식을 취해요.

기본: Intl.Segmenter API(Chrome 87+, Firefox 125+, Safari 14.1+)를 사용해 grapheme cluster를 올바르게 처리해요. 복잡한 이모지, 결합 마크, Zero Width Joiner 시퀀스를 올바르게 처리해요.
폴백: 오래된 브라우저는 Array.from()으로 폴백해 코드 포인트 기반 반복을 사용해요. 다만 이 방식은 여러 코드 포인트로 된 grapheme 시퀀스(예: 피부 톤 수정자가 붙은 이모지)를 분리할 수 있어요.

직접 count-graphemes 함수를 구현할 때도 복잡한 유니코드 문자를 견고하게 처리해야 한다면 Intl.Segmenter 사용을 고려해 보세요.

API

Attributes

Name	Description	Type	Default
type	type of input, see more in MDN	string	text
model-value / v-model	binding value	string / number	—
model-modifiers 2.11.5	v-model modifiers, reference Vue modifiers	object	—
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"
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	CircleClose
formatter	specifies the format of the value presented input.(only works when type is 'text')	Function	—
parser	specifies the value extracted from formatter input.(only works when type is 'text')	Function	—
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	—
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	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	—
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	{}
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	—

Events

Name	Description	Type
blur	triggers when Input blurs	Function
focus	triggers when Input focuses	Function
change	triggers when the input box loses focus or the user presses Enter, only if the modelValue has changed	Function
input	triggers when the Input value change	Function
clear	triggers when the Input is cleared by clicking the clear button	Function
keydown	triggers when a key is pressed down	Function
mouseleave	triggers when the mouse leaves the Input element	Function
mouseenter	triggers when the mouse enters the Input element	Function
compositionstart	triggers when the composition starts	Function
compositionupdate	triggers when the composition is updated	Function
compositionend	triggers when the composition ends	Function

Slots

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 }

Exposes

Name	Description	Type
blur	blur the input element	Function
clear	clear input value	Function
focus	focus the input element	Function
input	HTML input element	object
ref	HTML element, input or textarea	object
resizeTextarea	resize textarea	Function
select	select the text in input element	Function
textarea	HTML textarea element	object
textareaStyle	style of textarea	object
isComposing 2.8.0	is input composing	object
passwordVisible 2.13.7	whether the password is visible	object

FAQ

ElInput 컴포넌트의 너비가 clearable 때문에 늘어나는 이유는?

전형적인 이슈: #7287 참고: ElInput 컴포넌트는 기본 너비가 없어요. 그래서 clearable 아이콘이 표시되면 컴포넌트의 너비가 늘어나는데, width를 설정하면 해결할 수 있어요.

Input

Input

본문

기본 사용 (Basic usage)

비활성 (Disabled)

clearable (지우기 가능)

커스텀 클리어 아이콘 (Custom Clear Icon) 2.11.0

Formatter

비밀번호 상자 (Password box)

아이콘이 있는 Input (Input with icon)

Textarea

Autosize Textarea

혼합 입력 (Mixed input)

크기 (Sizes)

길이 제한 (Limit length)

Grapheme 세기 (Count graphemes) 2.13.7

API

Attributes

Events

Slots

Exposes

FAQ

ElInput 컴포넌트의 너비가 clearable 때문에 늘어나는 이유는?

더 알아보기 (Learn more)