Textarea

여러 줄의 텍스트를 입력하는 텍스트 영역 컴포넌트

개요

Textarea 컴포넌트는 네이티브 <textarea> 요소를 래핑하여 일관된 스타일과 크기를 제공합니다. field-sizing-content로 입력 내용에 따라 자동으로 높이가 조절됩니다.

주요 특징

• ✅ 기본 상태: 여러 줄의 텍스트를 입력 가능한 기본 상태 제공
• ✅ 포커스 상태: 포커스 시 시각적으로 구분되는 스타일
• ✅ 읽기 전용 상태: readOnly 상태 시각적 구분
• ✅ 오류 상태 표시: aria-invalid 속성으로 에러 스타일 적용
• ✅ Placeholder: 입력 전 가이드 텍스트 제공
• ✅ Resize: 세로 방향으로만 크기 조절 가능
• ✅ Sizes: xs, sm, md, lg, xl 5단계 크기
• ✅ 디자인 토큰: Input과 공유하는 테마 토큰 지원

Sizes

Textarea는 5가지 크기를 지원합니다. 기본값은 md입니다.

<Textarea size="xs" placeholder="Extra Small" />
<Textarea size="sm" placeholder="Small" />
<Textarea size="md" placeholder="Medium (기본)" />
<Textarea size="lg" placeholder="Large" />
<Textarea size="xl" placeholder="Extra Large" />

사용 예시

기본 상태

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

<Textarea placeholder="내용을 입력하세요" />

포커스 상태

포커스 시 시각적으로 구분되는 스타일을 제공합니다. 클릭하거나 Tab 키로 포커스하면 focus-visible 스타일이 적용됩니다.

<Textarea placeholder="클릭하거나 Tab으로 포커스하세요" />

읽기 전용 상태

읽기 전용(readOnly) 상태를 시각적으로 구분합니다. 입력은 불가하지만 텍스트 선택은 가능합니다.

<Textarea readOnly defaultValue="읽기 전용 내용입니다." />

오류 상태 표시

오류 발생 시 aria-invalid 속성으로 에러 상태를 시각적으로 표현합니다.

<Textarea aria-invalid defaultValue="잘못된 입력" />

Placeholder 제공

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

<Textarea placeholder="메시지를 입력하세요" />
<Textarea placeholder="리포트 요약을 작성하세요" />

Resize Handle 제공 / Resize 방향 제한

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

{/* rows 지정 시 고정 높이 + 세로 리사이즈 */}
<Textarea rows={4} placeholder="세로 방향으로 크기 조절 가능" />
 
{/* rows 미지정 시 자동 높이 조절 */}
<Textarea placeholder="자동 높이: 내용에 따라 높이 조절" />

입력 가능 제어

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

<Textarea disabled defaultValue="비활성화 상태" />
<Textarea readOnly defaultValue="읽기 전용 상태" />

API Reference

Props

<textarea> 요소의 기본 HTML 속성을 모두 지원합니다.

Events

기본 사용법

import { Textarea } from "@vortex/ui-foundation"
 
<Textarea placeholder="내용을 입력하세요" />
<Textarea size="sm" placeholder="작은 크기" />
<Textarea disabled />
<Textarea readOnly defaultValue="읽기 전용" />
<Textarea rows={4} placeholder="고정 높이" />

접근성

시맨틱 마크업

• 네이티브 <textarea> 요소 기반
• aria-invalid 속성으로 유효성 검증 에러 상태 전달
• 포커스 링 자동 적용 (focus-visible)

권장 사항

• ✅ Label과 함께 사용하여 접근성 보장 (htmlFor와 id 연결)
• ✅ 명확한 placeholder 텍스트 제공
• ✅ 에러 상태 시 aria-invalid 속성 사용
• ❌ placeholder만으로 라벨을 대체하지 않기

관련 컴포넌트

• Input: 한 줄 텍스트 입력
• Label: 라벨
• Field: 라벨, 설명, 에러를 포함하는 폼 필드 래퍼