Textarea

여러 줄 자유 입력을 native textarea의 form·keyboard·resize 동작과 함께 제공합니다.

예제

사용해야 할 때

문의 내용, 배송 메모, 설명처럼 줄바꿈이 가능한 자유 형식 text를 입력받을 때 사용합니다. 입력 길이와 form 제출은 native textarea 계약을 그대로 따릅니다.

사용하지 말아야 할 때

이름이나 검색어처럼 한 줄 값에는 TextField를 사용합니다. 자동 높이 증가, Markdown 편집, rich text, 내장 글자 수 표시는 이 컴포넌트의 범위가 아닙니다.

구조

root 안에 visible label, native textarea, optional description, optional alert error가 순서대로 배치됩니다. description과 error ID는 textarea ID에서 안정적으로 파생됩니다.

크기와 변형

medium은 48px, large는 56px의 최소 control height와 각 padding tier를 사용합니다. 기본 rows={4}가 실제 내용 높이를 정합니다. resize는 vertical과 none만 제공하며 수평 크기 조절은 허용하지 않습니다.

상태와 동작

상태 우선순위는 Disabled > Error > Focus > Default입니다. 기본값은 size="medium", resize="vertical", rows={4}이고 explicit rows, controlled/uncontrolled value, maxLength, required, name, form props는 native 동작을 유지합니다.

반응형 동작

control은 available width를 채우되 max-inline-size: 100%와 hidden horizontal overflow를 유지합니다. 긴 값은 줄바꿈되며 vertical resize 이후에도 컨테이너 너비를 넘지 않습니다.

접근성

visible label은 textarea와 직접 연결됩니다. aria-describedby는 description, error, caller IDs 순서로 중복 없이 합쳐집니다. errorMessage는 role="alert", aria-invalid="true", aria-errormessage를 소유하고 disabled에서도 오류 의미를 잃지 않습니다.

React 예제

import { Textarea } from '@hds/react';
import '@hds/react/styles.css';

export function DeliveryNote() {
  return (
    <Textarea
      description="배송 담당자에게 전달할 내용을 입력하세요."
      label="배송 메모"
      maxLength={200}
      name="deliveryNote"
      rows={6}
    />
  );
}

API

사용 토큰

• size/control/medium, size/control/large, radius/md
• space/2, space/4, space/8, space/12, space/16, space/20
• font/*, color/bg/*, color/text/*, color/border/*, color/status/danger*, color/focus/ring

Figma

Textarea component set은 Size 2 × State 4 = 8 variants와 Label, Value, Description, Error TEXT properties를 제공합니다. 기본 specimen은 320px 너비의 4-row 표현이며, 48/56px minimum tier, padding, radius, semantic state colors, typography가 library token에 연결되어 있습니다.

지원 상태