Skip to Content

Textarea

여러 줄의 텍스트를 입력할 수 있는 폼 컴포넌트


개요

Textarea는 여러 줄의 텍스트 입력을 위한 폼 컴포넌트입니다. 글자 수 카운터 기능을 내장하고 있으며, FormItem을 통해 레이블, 설명, 에러 메시지를 지원합니다.

주요 특징

  • 기본 상태: 여러 줄의 텍스트를 입력 가능한 기본 상태 제공
  • 필수값 표시: Label 좌측에 * 표시
  • 포커스 상태: 포커스 시 시각적으로 구분되는 스타일
  • 읽기 전용 상태: readOnly 상태 시각적 구분
  • 오류 상태 표시: error prop으로 에러 메시지와 스타일 자동 적용
  • 레이블 제공: label, labelWidth, orientation으로 레이블 배치
  • 설명 문구 표시: description prop으로 추가 설명 제공
  • Placeholder: 입력 전 가이드 텍스트 제공
  • 글자 수 표시: showCount + maxLength로 실시간 글자 수 카운터
  • Resize: 세로 방향으로만 크기 조절 가능
  • 디자인 토큰: 테마 커스터마이징 지원

Sizes


사용 예시

기본 상태

여러 줄의 텍스트를 입력 가능한 기본 상태를 제공합니다.

필수값 표시

필수 입력 항목은 Label 좌측에 *(Asterisk)를 표시합니다.

포커스 상태

포커스 시 시각적으로 구분되는 스타일을 제공합니다.

읽기 전용 상태

읽기 전용(readOnly) 상태를 시각적으로 구분합니다.

오류 상태 표시

오류 발생 시 error prop으로 에러 메시지를 표시하고, 오류 스타일이 자동 적용됩니다.

레이블 제공

레이블(Label)을 제공하며, orientation으로 배치 방향을 설정합니다.

설명 문구 표시

Title 외 추가 설명(Description)을 함께 표시할 수 있습니다.

간단한 자기소개를 입력해주세요

Placeholder 제공

입력 전 가이드 텍스트를 Placeholder로 제공하며, 입력 시 해당 텍스트는 제거됩니다.

글자 수 표시

입력 글자 수를 실시간 표시하며, ‘현재 글자 수 / 최대 글자 수’ 형태로 표기합니다.

0 / 500
29 / 200

Resize Handle 제공 / Resize 방향 제한

Textarea의 크기를 세로 방향(Vertical)으로만 조절할 수 있습니다. rows 지정 시 고정 높이에서 리사이즈 핸들이 제공됩니다.

입력 가능 제어

읽기 전용 상태에서는 입력이 불가합니다. disabledreadOnly로 입력 가능 여부를 제어합니다.

프로젝트팀 구현 항목: 아래 기능은 프로젝트 요구사항에 맞춰 직접 구현합니다.

  • 기본 높이 기준 설정: 입력 필드의 높이는 예상 입력량을 기준으로 설정

API Reference

Props

PropTypeDefaultDescription
showCountboolean-글자 수 카운터 표시
maxLengthnumber-최대 글자 수
rowsnumber-표시 행 수 (지정 시 field-sizing-fixed 적용)
size"xs" | "sm" | "md" | "lg" | "xl"-컴포넌트 크기
disabledbooleanfalse비활성화 여부
readOnlybooleanfalse읽기 전용 여부
labelstring-필드 레이블
labelWidthstring | number-레이블 너비
labelAlign"start" | "center" | "end"-레이블 가로 정렬
labelVerticalAlign"start" | "center" | "end"-레이블 세로 정렬
requiredbooleanfalse필수 여부 (Label에 * 표시)
orientation"horizontal" | "vertical""horizontal"레이블-필드 배치 방향
descriptionstring-설명 텍스트
errorstring-에러 메시지
classNamestring-추가 CSS 클래스

<textarea> 요소의 기본 HTML 속성(placeholder, value, defaultValue 등)을 모두 지원합니다.

Events

EventTypeDescription
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을 제공하여 입력 목적 전달
  • showCountmaxLength로 입력 제한 안내
  • ✅ 에러 상태에서 구체적 메시지 제공
  • ❌ placeholder만으로 레이블 대체 지양

관련 컴포넌트

Last updated on