Textarea

라벨, 높이 설정, 줄바꿈 정규화 등을 내장한 여러 줄 텍스트 입력 컴포넌트

개요

Cals Textarea는 Foundation Textarea를 래핑하여 CALS 제품의 여러 줄 텍스트 입력 UI를 선언적으로 구현하는 컴포넌트입니다. 폼 레이블, 높이 설정, 읽기 전용 등 CALS에서 자주 쓰이는 입력 처리를 prop으로 제공합니다.

주요 특징

• ✅ controlled / uncontrolled: value/onChange 또는 defaultValue로 값 관리
• ✅ 높이 설정: rows로 입력란의 세로 높이를 행 단위로 지정
• ✅ 줄바꿈 정규화: lineBreakNormalize로 리터럴 줄바꿈 문자열을 실제 줄바꿈으로 변환
• ✅ FormItem 내장: label/required/description/error prop으로 폼 레이블 자동 래핑
• ✅ 라벨 도움말: labelTooltip으로 레이블 옆 도움말 아이콘 표시
• ✅ 가시성/포커스 제어: visible prop, ref.focus()/blur()/element
• ✅ 디자인 토큰: 조건부 토큰 오버라이드 (prop이 있을 때만 적용)

기본 사용

placeholder로 입력 전 안내 문구를 표시합니다.

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

기본값 설정

defaultValue로 초기 기본값을 지정합니다.

<Textarea defaultValue="기본값" />

크기

size prop으로 입력란 크기를 지정합니다. xs / sm / md / lg / xl을 지원합니다.

<Textarea size="xs" />
<Textarea size="sm" />
<Textarea size="md" />
<Textarea size="lg" />
<Textarea size="xl" />

에디터 높이

rows prop으로 입력란의 세로 높이를 행 단위로 설정합니다.

<Textarea rows={3} placeholder="3행" />
<Textarea rows={6} placeholder="6행" />

비활성화 / 읽기 전용

disabled, readOnly는 모두 비활성화된 외관으로 표시되며 편집할 수 없습니다.

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

레이블 / 필수 입력

label로 레이블을 표시하고, required로 필수 표시 기호(*)를 추가합니다.

<Textarea label="메모" placeholder="메모를 입력하세요" />
<Textarea label="내용" required placeholder="필수 입력" />

레이블 위치

orientation=“horizontal”이면 레이블이 입력란 왼쪽에 배치됩니다.

<Textarea label="내용" orientation="horizontal" labelWidth={80} />

라벨 도움말

labelTooltip 지정 시 레이블 옆 아이콘에 마우스를 올리면 도움말이 표시됩니다.

<Textarea label="설명" labelTooltip="최대 500자까지 입력할 수 있습니다." />

글자 수 제한

maxLength로 최대 글자 수를 제한합니다. 초과 입력은 차단됩니다.

<Textarea maxLength={100} minLength={10} />

줄바꿈 정규화

lineBreakNormalize=true이면 저장 데이터에 포함된 리터럴 줄바꿈 문자열(\r, \n)을 실제 줄바꿈으로 변환하여 여러 줄로 표시합니다.

<Textarea lineBreakNormalize value={"첫 번째 줄\\n두 번째 줄"} />

스타일 설정

backgroundColor, color, borderColor 등으로 디자인 토큰을 오버라이드합니다.

<Textarea
  backgroundColor="#eef2ff"
  color="#1e3a8a"
  borderColor="#6366f1"
  defaultValue="스타일 오버라이드"
/>

API Reference

Props

Events

Ref

접근성

권장 사항

• ✅ label 또는 aria-label로 입력란의 목적을 명확히 제공하세요.
• ✅ 필수 입력은 required로 설정하여 스크린 리더에 전달하세요.
• ❌ placeholder만으로 레이블을 대체하지 마세요. 값 입력 시 사라집니다.

관련 컴포넌트

• Foundation Textarea: 기본 여러 줄 입력 컴포넌트
• FormItem: 폼 레이블 래퍼
• Cals Input: 단일 라인 텍스트 입력 컴포넌트