Project Information

Textarea / RHFTextarea

controlled usage와 React Hook Form 연동 기준으로 Textarea와 RHFTextarea의 주요 props와 사용 패턴을 정리한 가이드 페이지입니다.

Textarea

Textarea / controlled usage

Textarea는 value와 onChange를 외부 상태로 관리하는 controlled usage를 기준으로 정리한 멀티라인 입력 컴포넌트입니다.

Prop

value

string | number | readonly string[] | undefined

현재 입력값을 외부 상태로 관리합니다. clear 버튼과 메시지 상태도 이 값을 기준으로 동작합니다.

Prop

isClearable | onClear

boolean | () => void

default: false

clear 버튼은 isClearable이 true이고, value가 있으며, onClear가 제공되고, disabled/readOnly가 아닐 때만 노출됩니다.

Prop

rows | resize

number | "none" | "vertical"

rows는 기본 높이를 조정하고, resize는 세로 리사이즈 허용 여부만 제어합니다. 좌우 리사이즈는 UI 깨짐 방지를 위해 지원하지 않습니다.

Prop

infoMessage | errorMessage

string

default: ""

입력 필드 아래에 안내 메시지나 에러 메시지를 노출합니다.

여러 줄 입력 아래에도 보조 설명을 함께 노출할 수 있습니다.

에러 메시지를 표시하면 error 스타일이 적용됩니다.

Prop

native textarea props

name | maxLength | spellCheck | autoComplete | wrap ...

- Textarea에서 정의하지 않은 native textarea props는 내부 textarea에 그대로 전달됩니다.
- defaultValue는 지원하지 않고 value 기반 controlled usage를 전제로 하며,
- aria-invalid는 errorMessage 기준으로 내부에서 설정합니다.

0/120

Prop

disabled | readOnly

boolean

default: false

읽기 전용 입력값

React Hook Form

RHFTextarea / 폼 연동

RHFTextarea는 useController로 Textarea를 React Hook Form 필드와 연결한 래퍼 컴포넌트입니다.

Prop

Textarea props 확장 + RHFComponentProps

RHFComponentProps<TFormValues, TFieldName, TextareaProps, RHFValueInputManagedProps> & { formatValue?: (value: string) => string; }

RHFTextarea는 Textarea props를 기반으로 하고, name/value/defaultValue/onBlur/onChange는 RHF가 관리합니다. clear 버튼을 쓰면 RHF 값이 먼저 빈 문자열로 정리된 뒤 onClear가 호출되고, formatValue를 전달하면 가공된 값을 RHF 상태에 반영합니다.

Prop

rules

required | validate | minLength ...

rules를 통해 멀티라인 입력 검증을 연결할 수 있습니다. 아래 예시는 공백만 입력한 경우와 최소 길이를 함께 검증합니다.

Prop

formatValue

(value: string) => string

formatValue를 전달하면 RHFTextarea 내부 onChange에서 값을 가공한 뒤 field.onChange로 전달할 수 있습니다.
아래 예시는 입력 줄 수를 최대 5줄까지만 허용하도록 제한합니다.

Prop

native textarea props

rows | maxLength | spellCheck | resize | disabled ...

RHF 연결과 함께 textarea native props와 Textarea UI props를 함께 전달할 수 있습니다.

Props Table

Textarea props 한눈에 보기

Textarea에서 자주 사용하는 핵심 UI props와 native textarea 위임 규칙을 표로 정리했습니다.

Prop	Type	Default	Required	Description
`value`	`string \| number \| readonly string[] \| undefined`	`undefined`	Optional	현재 입력값을 외부 상태로 관리합니다. Textarea는 value 기반 controlled usage를 전제로 합니다.
`placeholder`	`string`	`"내용을 입력해주세요"`	Optional	입력값이 비어 있을 때 표시할 안내 문구입니다.
`rows`	`number`	`4`	Optional	기본 textarea 높이를 조절합니다.
`resize`	`TextareaResize`	`"vertical"`	Optional	사용자 리사이즈 허용 범위를 제어합니다. UI 깨짐 방지를 위해 horizontal은 지원하지 않습니다.
`isClearable`	`boolean`	`false`	Optional	값이 있고 onClear가 있으며 disabled/readOnly가 아닐 때 clear 버튼을 노출합니다.
`onClear`	`() => void`	`undefined`	Optional	clear 버튼 클릭 시 호출되는 콜백입니다.
`infoMessage`	`string`	`""`	Optional	입력 필드 아래에 보조 안내 메시지를 노출합니다.
`errorMessage`	`string`	`""`	Optional	에러 메시지를 노출하고 error 스타일 및 aria-invalid를 적용합니다.
`disabled`	`boolean`	`false`	Optional	입력과 clear 상호작용을 비활성화합니다.
`readOnly`	`boolean`	`false`	Optional	입력값 수정은 막되 포커스와 선택은 허용합니다.
`id / className`	`string`	`undefined`	Optional	textarea id와 루트 wrapper 커스텀 클래스를 지정합니다.
`name / maxLength / spellCheck / wrap / autoComplete ...`	`native textarea props`	`inherited`	Optional	Textarea에서 별도로 제어하지 않는 native textarea props는 내부 textarea에 그대로 전달됩니다.

TextareaProps는 defaultValue, id, placeholder, readOnly, value 같은 일부 native textarea props를 자체 규칙으로 다시 정의합니다. aria-invalid는 errorMessage 기준으로 내부에서 처리됩니다.

Props Table

RHFTextarea props 한눈에 보기

RHFTextarea에서 사용하는 RHF 제어 props와 Textarea 상속 props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`name`	`FieldPath<TFormValues>`	-	Required	React Hook Form 필드 경로입니다.
`control`	`Control<TFormValues>`	-	Required	useForm에서 받은 control 객체를 전달합니다.
`rules`	`UseControllerProps['rules']`	`undefined`	Optional	required, validate, minLength 같은 검증 규칙을 useController 규격으로 전달합니다.
`defaultValue`	`string`	`undefined`	Optional	필요할 때만 사용하며, 일반적으로는 useForm의 defaultValues를 우선 사용합니다.
`shouldUnregister`	`boolean`	`false`	Optional	조건부 렌더링으로 필드가 사라질 때 RHF 상태에서도 값을 제거할지 결정합니다.
`formatValue`	`(value: string) => string`	`undefined`	Optional	onChange 시 입력값을 가공한 뒤 RHF 상태에 반영합니다.
`disabled`	`boolean`	`false`	Optional	useController와 실제 Textarea에 동시에 반영되어 필드 업데이트와 상호작용을 막습니다.
`errorMessage`	`string`	`field error message`	Optional	RHF 검증 메시지가 없을 때만 fallback 에러 메시지로 사용됩니다.
`rows / resize / isClearable / onClear ...`	`Textarea inherited props`	`inherited`	Optional	RHF가 직접 관리하지 않는 Textarea UI props와 native textarea props는 그대로 전달할 수 있습니다.

RHFTextareaProps는 RHFComponentProps<TFormValues, TFieldName, TextareaProps, RHFValueInputManagedProps>에 formatValue를 추가한 구조입니다. 그래서 name, value, defaultValue, onBlur, onChange는 RHF가 관리하고, 나머지 Textarea UI props만 직접 전달하는 패턴입니다.