Textarea
여러 줄의 텍스트를 입력할 수 있는 폼 컴포넌트
개요
Textarea는 여러 줄의 텍스트 입력을 위한 폼 컴포넌트입니다. 글자 수 카운터 기능을 내장하고 있으며, FormItem을 통해 레이블, 설명, 에러 메시지를 지원합니다.
주요 특징
- ✅ 기본 상태: 여러 줄의 텍스트를 입력 가능한 기본 상태 제공
- ✅ 필수값 표시: Label 좌측에
*표시 - ✅ 포커스 상태: 포커스 시 시각적으로 구분되는 스타일
- ✅ 읽기 전용 상태: readOnly 상태 시각적 구분
- ✅ 오류 상태 표시: error prop으로 에러 메시지와 스타일 자동 적용
- ✅ 레이블 제공: label, labelWidth, orientation으로 레이블 배치
- ✅ 설명 문구 표시: description prop으로 추가 설명 제공
- ✅ Placeholder: 입력 전 가이드 텍스트 제공
- ✅ 글자 수 표시: showCount + maxLength로 실시간 글자 수 카운터
- ✅ Resize: 세로 방향으로만 크기 조절 가능
- ✅ 디자인 토큰: 테마 커스터마이징 지원
Sizes
Preview
사용 예시
기본 상태
여러 줄의 텍스트를 입력 가능한 기본 상태를 제공합니다.
Preview
필수값 표시
필수 입력 항목은 Label 좌측에 *(Asterisk)를 표시합니다.
Preview
포커스 상태
포커스 시 시각적으로 구분되는 스타일을 제공합니다.
Preview
읽기 전용 상태
읽기 전용(readOnly) 상태를 시각적으로 구분합니다.
Preview
오류 상태 표시
오류 발생 시 error prop으로 에러 메시지를 표시하고, 오류 스타일이 자동 적용됩니다.
Preview
레이블 제공
레이블(Label)을 제공하며, orientation으로 배치 방향을 설정합니다.
Preview
설명 문구 표시
Title 외 추가 설명(Description)을 함께 표시할 수 있습니다.
Preview
간단한 자기소개를 입력해주세요
Placeholder 제공
입력 전 가이드 텍스트를 Placeholder로 제공하며, 입력 시 해당 텍스트는 제거됩니다.
Preview
글자 수 표시
입력 글자 수를 실시간 표시하며, ‘현재 글자 수 / 최대 글자 수’ 형태로 표기합니다.
Preview
Resize Handle 제공 / Resize 방향 제한
Textarea의 크기를 세로 방향(Vertical)으로만 조절할 수 있습니다. rows 지정 시 고정 높이에서 리사이즈 핸들이 제공됩니다.
Preview
입력 가능 제어
읽기 전용 상태에서는 입력이 불가합니다. disabled와 readOnly로 입력 가능 여부를 제어합니다.
Preview
프로젝트팀 구현 항목: 아래 기능은 프로젝트 요구사항에 맞춰 직접 구현합니다.
- 기본 높이 기준 설정: 입력 필드의 높이는 예상 입력량을 기준으로 설정
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
showCount | boolean | - | 글자 수 카운터 표시 |
maxLength | number | - | 최대 글자 수 |
rows | number | - | 표시 행 수 (지정 시 field-sizing-fixed 적용) |
size | "xs" | "sm" | "md" | "lg" | "xl" | - | 컴포넌트 크기 |
disabled | boolean | false | 비활성화 여부 |
readOnly | boolean | false | 읽기 전용 여부 |
label | string | - | 필드 레이블 |
labelWidth | string | number | - | 레이블 너비 |
labelAlign | "start" | "center" | "end" | - | 레이블 가로 정렬 |
labelVerticalAlign | "start" | "center" | "end" | - | 레이블 세로 정렬 |
required | boolean | false | 필수 여부 (Label에 * 표시) |
orientation | "horizontal" | "vertical" | "horizontal" | 레이블-필드 배치 방향 |
description | string | - | 설명 텍스트 |
error | string | - | 에러 메시지 |
className | string | - | 추가 CSS 클래스 |
<textarea>요소의 기본 HTML 속성(placeholder,value,defaultValue등)을 모두 지원합니다.
Events
| Event | Type | Description |
|---|---|---|
onChange | (e: ChangeEvent<HTMLTextAreaElement>) => void | 값 변경 시 호출 |
onFocus | (e: FocusEvent<HTMLTextAreaElement>) => void | 포커스 시 호출 |
onBlur | (e: FocusEvent<HTMLTextAreaElement>) => void | 블러 시 호출 |
기본 사용법
import { Textarea } from "@vortex/ui-icignal"
<Textarea label="메모" placeholder="내용을 입력하세요" />
<Textarea label="요약" showCount maxLength={500} />
<Textarea label="설명" required error="필수 항목입니다" />접근성
ARIA 속성
<Textarea label="설명" error="설명을 입력해주세요" />권장 사항
- ✅
label을 제공하여 입력 목적 전달 - ✅
showCount와maxLength로 입력 제한 안내 - ✅ 에러 상태에서 구체적 메시지 제공
- ❌ placeholder만으로 레이블 대체 지양
관련 컴포넌트
- Input: 한 줄 텍스트 입력
- InputNumber: 숫자 입력
- InputPassword: 비밀번호 입력