Project Information

Password / RHFPassword

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

Password

Password / controlled usage

Password는 value와 onChange를 외부 상태로 관리하는 controlled usage를 기준으로 정리한 비밀번호 입력 컴포넌트입니다. Textfield UI에 보기/숨기기 토글을 더한 형태입니다.

Prop

Textfield props 확장

Omit<TextfieldProps, "children" | "type"> & { defaultIsPasswordVisible?: boolean; hidePasswordTitle?: string; showPasswordTitle?: string; }

- Password는 Textfield props를 확장한 래퍼 컴포넌트입니다.
- value, onChange, isClearable, infoMessage, errorMessage 같은 Textfield props를 그대로 사용할 수 있습니다.
- controlled usage에서 clear 버튼은 isClearable이 true이고, value가 있으며, onClear가 제공되고, disabled/readOnly가 아닐 때만 노출됩니다.
- children과 type은 내부에서 비밀번호 토글 버튼과 password/text 전환으로 관리합니다.
- clear 버튼을 누르면 전달한 onClear가 실행되고, 비밀번호 표시 상태는 다시 숨김으로 돌아갑니다.

Textfield props를 그대로 사용하면서 비밀번호 보기/숨기기 토글을 제공합니다.

Prop

defaultIsPasswordVisible | hidePasswordTitle | showPasswordTitle

boolean | string

초기 표시 상태와 비밀번호 토글 버튼의 접근성 텍스트를 제어합니다. clear 버튼을 누르면 표시 상태는 다시 숨김으로 돌아갑니다.

Prop

native input props

name | maxLength | autoComplete | placeholder ...

Textfield에서 허용하는 text-like native input props도 Password에서 그대로 사용할 수 있습니다.

Prop

disabled | readOnly

boolean

default: false

disabled는 입력과 토글 버튼을 모두 비활성화하고, readOnly는 직접 입력과 clear 버튼을 막지만 보기/숨기기 토글은 유지합니다.

readOnly에서도 비밀번호 보기/숨기기 토글은 유지됩니다.

React Hook Form

RHFPassword / 폼 연동

RHFPassword는 RHFTextfield를 기반으로 Password UI를 React Hook Form 필드와 연결한 래퍼 컴포넌트입니다.

Prop

RHFTextfield props 확장

Omit<RHFTextfieldProps<TFieldValues, TName>, "children" | "type"> & { defaultIsPasswordVisible?: boolean; hidePasswordTitle?: string; showPasswordTitle?: string; }

- RHFPassword는 RHFTextfield props를 확장합니다.
- RHFTextfield는 Textfield UI props를 기반으로 하므로 isClearable, infoMessage, errorMessage 같은 Textfield props도 함께 사용할 수 있습니다.
- clear 버튼은 isClearable이 true이고 값이 있을 때 보이며, 클릭하면 RHF 값이 먼저 빈 문자열로 정리된 뒤 표시 상태가 다시 숨김으로 돌아갑니다.
- children과 type은 내부에서 비밀번호 토글 버튼과 password/text 전환으로 관리합니다.

Prop

rules

required | minLength | validate ...

비밀번호 필드 검증은 RHF rules로 연결하고, 토글 상태는 RHFPassword 내부 UI 상태로 처리합니다. clear 시에는 다시 숨김 상태로 돌아갑니다.

Prop

disabled | readOnly

boolean

default: false

RHFPassword도 Textfield 상태 props를 그대로 상속합니다. disabled는 입력과 토글 버튼을 모두 막고, readOnly는 직접 입력과 clear 버튼을 막지만 보기/숨기기 토글은 유지합니다.

비활성화 비밀번호

읽기 전용 비밀번호

readOnly에서도 비밀번호 보기/숨기기 토글은 유지됩니다.

Prop

defaultIsPasswordVisible | native input props

boolean | autoComplete | maxLength | placeholder ...

RHFPassword에서도 초기 표시 상태와 Textfield 기반 native input props를 함께 설정할 수 있습니다.

Props Table

Password props 한눈에 보기

Password에서 자주 사용하는 비밀번호 토글 관련 props와 Textfield 상속 props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`value`	`string \| number \| readonly string[] \| undefined`	`undefined`	Optional	현재 입력값을 외부 상태로 관리합니다.
`defaultIsPasswordVisible`	`boolean`	`false`	Optional	초기 비밀번호 표시 상태를 제어합니다.
`hidePasswordTitle / showPasswordTitle`	`string`	`"비밀번호 숨기기" \| "비밀번호 보기"`	Optional	토글 버튼의 접근성 title을 커스터마이즈합니다.
`isClearable / onClear`	`boolean \| () => void`	`false \| undefined`	Optional	clear 버튼은 Textfield와 같은 조건으로 노출되며, clear 시 표시 상태는 다시 숨김으로 돌아갑니다.
`placeholder \| infoMessage \| errorMessage`	`string`	`Textfield defaults`	Optional	비밀번호 입력에도 Textfield의 보조 메시지와 에러 메시지 규칙을 그대로 적용합니다.
`disabled`	`boolean`	`false`	Optional	입력과 비밀번호 토글 버튼을 모두 비활성화합니다.
`readOnly`	`boolean`	`false`	Optional	직접 입력과 clear 버튼은 막지만 보기/숨기기 토글은 유지합니다.
`name / maxLength / autoComplete / placeholder ...`	`Textfield inherited props`	`inherited`	Optional	Textfield에서 허용하는 native input props와 UI props를 함께 전달할 수 있습니다.

PasswordProps는 TextfieldProps에서 children과 type을 숨기고, 비밀번호 토글용 prop만 추가한 타입입니다. 내부에서 type은 "password"와 "text" 사이를 토글합니다.

Props Table

RHFPassword props 한눈에 보기

RHFPassword에서 사용하는 RHF 제어 props와 비밀번호 토글 관련 추가 props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`name`	`FieldPath<TFormValues>`	-	Required	React Hook Form 필드 경로입니다.
`control`	`Control<TFormValues>`	-	Required	useForm에서 받은 control 객체를 전달합니다.
`rules`	`RHFTextfieldProps['rules']`	`undefined`	Optional	비밀번호 검증 규칙을 RHFTextfield와 동일하게 연결합니다.
`defaultValue`	`string`	`undefined`	Optional	필요할 때만 사용하며, 일반적으로는 useForm의 defaultValues를 우선 사용합니다.
`shouldUnregister`	`boolean`	`false`	Optional	조건부 렌더링으로 필드가 사라질 때 RHF 상태에서도 값을 제거할지 결정합니다.
`defaultIsPasswordVisible`	`boolean`	`false`	Optional	초기 비밀번호 표시 상태를 제어합니다.
`hidePasswordTitle / showPasswordTitle`	`string`	`"비밀번호 숨기기" \| "비밀번호 보기"`	Optional	토글 버튼의 접근성 title을 커스터마이즈합니다.
`formatValue`	`(value: string) => string`	`undefined`	Optional	RHFTextfield에서 상속한 값 가공 로직도 그대로 사용할 수 있습니다.
`isClearable / infoMessage / readOnly / disabled ...`	`RHFTextfield inherited props`	`inherited`	Optional	RHFTextfield와 Textfield의 UI props를 그대로 전달할 수 있습니다.

RHFPasswordProps는 RHFTextfieldProps에서 children과 type을 숨기고, 비밀번호 토글용 prop만 추가한 타입입니다. 내부에서 type은 "password"와 "text" 사이를 토글합니다.