Project Information

Search / RHFSearch

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

Search / controlled usage

Search는 value와 onChange를 외부 상태로 관리하는 controlled usage를 기준으로 정리한 검색 입력 컴포넌트입니다. Textfield UI에 검색 버튼 동작을 더한 형태입니다.

Prop

Textfield props 확장

Omit<TextfieldProps, "children" | "type"> & { onSearch?: () => void; searchButtonTitle?: string; searchButtonType?: "button" | "submit" | "reset"; }

- Search는 Textfield props를 확장한 래퍼 컴포넌트입니다.
- value, onChange, isClearable, infoMessage, errorMessage 같은 Textfield props를 그대로 사용할 수 있습니다.
- controlled usage에서 clear 버튼은 isClearable이 true이고, value가 있으며, onClear가 제공되고, disabled/readOnly가 아닐 때만 노출됩니다.
- children과 type은 내부에서 검색 버튼과 text 타입으로 고정합니다.
- searchButtonType을 지정하지 않으면 onSearch가 있을 때는 button, 없을 때는 submit으로 동작합니다.

Textfield props를 그대로 사용하면서 검색 버튼을 함께 노출합니다.

Prop

onSearch | searchButtonTitle | searchButtonType

() => void | string | "button" | "submit" | "reset"

검색 버튼 클릭 동작, 접근성 텍스트, 버튼 type을 설정합니다. form 내부에서는 submit 버튼처럼 사용할 수도 있습니다.

Prop

native input props

name | maxLength | inputMode | autoComplete ...

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

Prop

disabled | readOnly

boolean

default: false

disabled는 입력과 검색 버튼을 모두 비활성화하고, readOnly는 직접 입력과 clear 버튼을 막지만 검색 버튼 액션은 유지합니다.

readOnly에서도 검색 버튼 클릭 동작은 유지됩니다.

React Hook Form

RHFSearch / 폼 연동

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

Prop

RHFTextfield props 확장

Omit<RHFTextfieldProps<TFieldValues, TName>, "children" | "type"> & { onSearch?: () => void; searchButtonTitle?: string; searchButtonType?: "button" | "submit" | "reset"; }

- RHFSearch는 RHFTextfield props를 확장합니다.
- RHFTextfield는 Textfield UI props를 기반으로 하므로 isClearable, infoMessage, errorMessage 같은 Textfield props도 함께 사용할 수 있습니다.
- clear 버튼은 isClearable이 true이고 값이 있을 때 보이며, 클릭하면 RHF 값이 먼저 빈 문자열로 정리된 뒤 onClear가 호출됩니다.
- children과 type은 내부에서 검색 버튼과 text 타입으로 고정합니다.
- searchButtonType을 지정하지 않으면 onSearch가 있을 때는 button, 없을 때는 submit으로 동작합니다.

Prop

rules | onSearch

RHFSearchProps<TFormValues, TFieldName>["rules"] | (() => void)

검색 버튼 액션은 onSearch로 분리하고, 실제 필드 검증은 RHFSearch가 상속한 RHFTextfield rules로 연결합니다.

Prop

searchButtonType

"button" | "submit" | "reset"

form 내부에서 검색 버튼을 submit 버튼처럼 쓰고 싶다면 searchButtonType을 지정할 수 있습니다.

Prop

disabled | readOnly

boolean

default: false

RHFSearch도 Textfield 상태 props를 그대로 상속합니다. disabled는 입력과 검색 버튼을 모두 막고, readOnly는 직접 입력과 clear 버튼을 막지만 검색 버튼 액션은 유지합니다.

비활성화 검색

읽기 전용 검색

readOnly에서도 검색 버튼 클릭 동작은 유지됩니다.

Prop

native input props

placeholder | inputMode | maxLength | autoComplete ...

RHFSearch에서도 RHFTextfield와 Textfield에서 허용하는 native input props를 그대로 전달할 수 있습니다.

Props Table

Search props 한눈에 보기

Search에서 자주 사용하는 검색 버튼 관련 props와 Textfield 상속 props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`value`	`string \| number \| readonly string[] \| undefined`	`undefined`	Optional	현재 입력값을 외부 상태로 관리합니다.
`onSearch`	`() => void`	`undefined`	Optional	검색 버튼 클릭 시 실행할 액션을 지정합니다.
`searchButtonTitle`	`string`	`"검색"`	Optional	검색 버튼의 접근성 title을 지정합니다.
`searchButtonType`	`"button" \| "submit" \| "reset"`	`onSearch ? "button" : "submit"`	Optional	form 내부에서 검색 버튼을 submit 버튼처럼 쓰고 싶을 때 지정합니다.
`isClearable / onClear`	`boolean \| () => void`	`false \| undefined`	Optional	Textfield와 동일한 clear 버튼 규칙을 따릅니다.
`placeholder \| infoMessage \| errorMessage`	`string`	`Textfield defaults`	Optional	검색 UI에도 Textfield의 보조 메시지와 에러 메시지 규칙을 그대로 적용합니다.
`disabled`	`boolean`	`false`	Optional	입력과 검색 버튼을 모두 비활성화합니다.
`readOnly`	`boolean`	`false`	Optional	직접 입력과 clear 버튼은 막지만 검색 버튼 액션은 유지합니다.
`name / inputMode / maxLength / autoComplete ...`	`Textfield inherited props`	`inherited`	Optional	Textfield에서 허용하는 native input props와 UI props를 함께 전달할 수 있습니다.

SearchProps는 TextfieldProps에서 children과 type을 숨기고, 검색 버튼용 prop만 추가한 타입입니다. 내부에서 type은 항상 "text"로 고정되고 검색 버튼이 자동 렌더링됩니다.

Props Table

RHFSearch props 한눈에 보기

RHFSearch에서 사용하는 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 상태에서도 값을 제거할지 결정합니다.
`onSearch`	`() => void`	`undefined`	Optional	검색 버튼 클릭 액션을 RHF submit과 별도로 연결할 수 있습니다.
`searchButtonTitle / searchButtonType`	`string \| "button" \| "submit" \| "reset"`	`"검색" \| inferred`	Optional	검색 버튼의 접근성 title과 버튼 type을 설정합니다.
`formatValue`	`(value: string) => string`	`undefined`	Optional	RHFTextfield에서 상속한 값 가공 로직도 그대로 사용할 수 있습니다.
`isClearable / infoMessage / readOnly / disabled ...`	`RHFTextfield inherited props`	`inherited`	Optional	RHFTextfield와 Textfield의 UI props를 그대로 전달할 수 있습니다.

RHFSearchProps는 RHFTextfieldProps에서 children과 type을 숨기고, 검색 버튼용 prop만 추가한 타입입니다. 내부에서 type은 항상 "text"로 고정됩니다.