Project Information

Switch / RHFSwitch

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

Switch

Switch / controlled usage

Switch는 checked와 onChange를 외부 상태로 관리하는 controlled usage를 기준으로 정리한 boolean 토글 컴포넌트입니다.

Prop

checked | onChange

boolean | React.ChangeEventHandler<HTMLInputElement>

controlled usage에서는 checked와 onChange를 함께 사용해 현재 토글 상태를 외부 상태로 제어합니다.

푸시 알림 받기

Prop

disabled | readOnly | isError

boolean

default: false

disabled는 상호작용을 막고, readOnly는 현재 토글 상태를 유지한 채 변경만 막습니다. isError는 시각 상태와 aria-invalid를 적용합니다.

disabled 상태

readOnly 상태

isError 상태

에러 상태를 표시한 예시입니다.

React Hook Form

RHFSwitch / 폼 연동

RHFSwitch는 Switch를 React Hook Form의 boolean 필드와 연결한 래퍼 컴포넌트입니다.

Prop

Switch props 확장 + RHFComponentProps

RHFComponentProps<TFormValues, TFieldName, SwitchProps, RHFCheckedInputManagedProps>

RHFSwitch는 Switch props를 기반으로 하고, checked/defaultChecked/defaultValue/name/onBlur/onChange는 RHF가 관리합니다. boolean 필드와 연결하면 ref와 checked 상태가 자동으로 연결되고, 초기값은 보통 useForm의 defaultValues로 둡니다.

Prop

shouldUnregister

boolean

default: false

shouldUnregister가 true이면 조건부 렌더링으로 필드가 사라질 때 RHF 상태에서도 해당 값을 제거합니다. 동적으로 나타났다 사라지는 토글 항목에 유용합니다.

Prop

disabled | readOnly | isError

boolean

default: false

RHFSwitch도 Switch 상태 props를 그대로 상속합니다. disabled는 RHF 필드 업데이트와 입력 상호작용을 막고, readOnly는 현재 값을 유지한 채 변경만 막습니다. isError는 RHF 검증 상태에 시각 에러 상태를 추가할 때 사용할 수 있습니다.

disabled 예시

readOnly 예시

isError 예시

에러 상태를 표시한 예시입니다.

Prop

rules

validate | required

필수 설정을 켜야 하는 규칙은 validate로 연결하는 방식이 가장 명확합니다.

Props Table

Switch props 한눈에 보기

Switch에서 자주 사용하는 핵심 props와 접근성 동작을 표로 정리했습니다.

Prop	Type	Default	Required	Description
`id`	`string`	`generated id`	Optional	직접 id를 주지 않으면 Field context id 또는 React useId 기반 id를 사용합니다.
`name`	`string`	`undefined`	Optional	폼 제출이나 네이티브 input 식별이 필요할 때 사용합니다.
`checked`	`boolean`	`undefined`	Optional	controlled usage에서 현재 토글 상태를 외부 값으로 제어합니다.
`defaultChecked`	`boolean`	`undefined`	Optional	uncontrolled usage에서 초기 토글 상태를 지정할 때 사용합니다.
`disabled`	`boolean`	`false`	Optional	비활성 상태를 적용해 상호작용을 막습니다.
`readOnly`	`boolean`	`false`	Optional	포커스와 읽기는 허용하되 클릭, 스페이스, 엔터로 값이 바뀌지 않게 막습니다.
`isError`	`boolean`	`false`	Optional	시각 에러 상태와 aria-invalid를 적용합니다. Field의 에러 상태와 합쳐집니다.
`onChange`	`React.ChangeEventHandler<HTMLInputElement>`	`undefined`	Optional	토글 상태 변경 시 호출됩니다. controlled usage에서는 checked와 함께 사용합니다.
`aria-describedby`	`string`	`merged ids`	Optional	직접 전달한 값에 Field 설명/에러 메시지 id가 있으면 함께 병합됩니다.
`className`	`string`	`undefined`	Optional	루트 wrapper에 커스텀 클래스를 추가합니다.

SwitchProps는 InputHTMLAttributes를 기반으로 하지만 type은 내부에서 항상 "checkbox", role은 "switch"로 고정됩니다. Field 안에서 사용할 때 일부 상태와 aria 값이 자동으로 병합됩니다.

Props Table

RHFSwitch props 한눈에 보기

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

Prop	Type	Default	Required	Description
`name`	`FieldPath<TFormValues>`	-	Required	React Hook Form 필드 경로입니다.
`control`	`Control<TFormValues>`	-	Required	useForm에서 받은 control 객체를 전달합니다.
`rules`	`UseControllerProps['rules']`	`undefined`	Optional	필수 동의 같은 검증 규칙을 useController 규격으로 전달합니다.
`defaultValue`	`boolean`	`undefined`	Optional	필요할 때만 사용하며, 일반적으로는 useForm의 defaultValues를 우선 사용합니다.
`shouldUnregister`	`boolean`	`false`	Optional	조건부 렌더링으로 필드가 사라질 때 RHF 상태에서도 값을 제거할지 결정합니다.
`disabled`	`boolean`	`false`	Optional	useController와 실제 Switch에 동시에 반영되어 필드 업데이트와 상호작용을 막습니다.
`readOnly`	`boolean`	`false`	Optional	Switch로 전달되어 현재 값을 유지한 채 변경만 막습니다.
`isError`	`boolean`	`false`	Optional	RHF validation error와 별도로 추가 시각 에러 상태를 강제할 때 사용합니다.
`id / aria-describedby / className`	`Switch inherited props`	`inherited`	Optional	RHF가 직접 관리하지 않는 Switch props는 그대로 전달할 수 있습니다.

RHFSwitchProps는 RHFComponentProps<TFormValues, TFieldName, SwitchProps, RHFCheckedInputManagedProps>형태입니다. 그래서 checked, defaultChecked, defaultValue, name, onBlur, onChange는 RHF가 관리하고, 나머지 Switch props만 직접 전달하는 패턴입니다.