Project Information

Textfield / RHFTextfield

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

Textfield

Textfield / controlled usage

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

Prop

value

string | number | readonly string[] | undefined

현재 입력값을 외부 상태로 관리합니다. clear 버튼이나 value 기반 UI는 이 값을 기준으로 동작합니다.

Prop

isClearable | onClear

boolean | () => void

default: false

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

Prop

children | isTextInputBlocked

React.ReactNode | boolean

- children은 입력 오른쪽 action 영역에 원하는 노드를 추가합니다.
- Search, Password 같은 파생 컴포넌트도 이 slot을 사용합니다.
- isTextInputBlocked는 직접 타이핑만 막고 액션 버튼 중심 흐름을 만들 때 사용합니다.

Prop

unit

string

default: ""

입력값 오른쪽에 단위를 고정 표시합니다.

원

개

Prop

infoMessage | errorMessage

string

default: ""

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

보조 설명을 함께 노출할 수 있습니다.

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

Prop

native input props

name | type | maxLength | inputMode | autoComplete ...

- Textfield에서 정의하지 않은 text-like input props는 내부 input에 그대로 전달됩니다.
- type은 text, password, email, tel, url, number만 허용합니다.
- defaultValue는 지원하지 않고 value 기반 controlled usage를 전제로 하며,
- aria-invalid는 errorMessage 기준으로 내부에서 설정합니다.

Prop

disabled | readOnly

boolean

default: false

원

React Hook Form

RHFTextfield / 폼 연동

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

Prop

Textfield props 확장 + RHFComponentProps

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

RHFTextfield는 Textfield props를 기반으로 하고, name/value/defaultValue/onBlur/onChange는 RHF가 관리합니다. 나머지 Textfield UI props와 native input props는 그대로 전달할 수 있으며, clear 버튼을 쓰면 RHF 값이 먼저 빈 문자열로 정리된 뒤 onClear가 호출됩니다. formatValue는 가공된 값을 RHF 상태에 반영합니다.

Prop

rules

required | validate | minLength ...

rules를 통해 필드 검증을 연결할 수 있습니다. 아래 예시는 공백만 입력한 경우도 에러로 처리합니다.

Prop

rules.pattern

RegExp

pattern 검증을 사용하면 숫자, 이메일처럼 정규식 기반 형식을 RHF에서 검증할 수 있습니다.

Prop

formatValue

(value: string) => string

formatValue를 전달하면 RHFTextfield 내부 onChange에서 값을 가공한 뒤 field.onChange로 전달할 수 있습니다.
아래 예시는 휴대전화 입력 중 하이픈을 자동으로 추가하고, submit 시에는 숫자만 남겨 payload를 정리합니다.

Prop

native input props

placeholder | inputMode | maxLength | disabled ...

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

Props Table

Textfield props 한눈에 보기

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

Prop	Type	Default	Required	Description
`value`	`string \| number \| readonly string[] \| undefined`	`undefined`	Optional	현재 입력값을 외부 상태로 관리합니다. Textfield는 value 기반 controlled usage를 전제로 합니다.
`placeholder`	`string`	`"내용을 입력해주세요"`	Optional	입력값이 비어 있을 때 표시할 안내 문구입니다.
`type`	`TextfieldInputType`	`"text" (native default)`	Optional	text-like input 타입만 허용합니다.
`children`	`React.ReactNode`	`undefined`	Optional	입력 오른쪽 action 영역에 커스텀 버튼이나 아이콘을 추가합니다.
`isTextInputBlocked`	`boolean`	`false`	Optional	직접 타이핑만 막고, 오른쪽 action 버튼 중심으로 상호작용하게 만들 때 사용합니다.
`unit`	`string`	`""`	Optional	입력값 오른쪽에 단위를 고정 표시합니다.
`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/action 상호작용을 비활성화합니다.
`readOnly`	`boolean`	`false`	Optional	입력값 수정은 막되 포커스와 선택은 허용합니다.
`id / className`	`string`	`undefined`	Optional	입력 id와 루트 wrapper 커스텀 클래스를 지정합니다.
`name / inputMode / maxLength / autoComplete ...`	`native text-like input props`	`inherited`	Optional	Textfield에서 별도로 제어하지 않는 native input props는 내부 input에 그대로 전달됩니다.

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

Props Table

RHFTextfield props 한눈에 보기

RHFTextfield에서 사용하는 RHF 제어 props와 Textfield 상속 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, pattern 같은 검증 규칙을 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와 실제 Textfield에 동시에 반영되어 필드 업데이트와 상호작용을 막습니다.
`errorMessage`	`string`	`field error message`	Optional	RHF 검증 메시지가 없을 때만 fallback 에러 메시지로 사용됩니다.
`placeholder / unit / isClearable / onClear ...`	`Textfield inherited props`	`inherited`	Optional	RHF가 직접 관리하지 않는 Textfield UI props와 native input props는 그대로 전달할 수 있습니다.

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