Project Information

Checkbox / CheckboxGroup / RHFCheckbox

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

Checkbox

Checkbox / controlled usage

Checkbox는 checked와 onChange를 외부 상태로 관리하는 controlled usage를 기준으로 정리한 단일 체크박스 컴포넌트입니다.

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 상태

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

Prop

CheckboxGroup

name | direction | disabled | readOnly | isError

CheckboxGroup은 여러 Checkbox에 공통 name, disabled, readOnly, isError 상태를 내려주는 그룹 레이아웃입니다. direction으로 row/column 배치를 바꿀 수 있습니다.

이메일 알림

문자 알림

앱 푸시 알림

React Hook Form

RHFCheckbox / 폼 연동

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

Prop

Checkbox props 확장 + RHFComponentProps

RHFComponentProps<TFormValues, TFieldName, CheckboxProps, RHFCheckedInputManagedProps>

RHFCheckbox는 Checkbox props를 기반으로 하고, checked/defaultChecked/defaultValue/name/onBlur/onChange는 RHF가 관리합니다. 단일 boolean 필드와 연결하면 ref와 checked 상태가 자동으로 연결되고, 초기값은 보통 useForm의 defaultValues로 두며 필요할 때만 RHFCheckbox의 defaultValue를 함께 사용할 수 있습니다.

Prop

shouldUnregister

boolean

default: false

shouldUnregister가 true이면 조건부 렌더링으로 필드가 사라질 때 RHF 상태에서도 해당 값을 제거합니다.

Prop

disabled | readOnly | isError

boolean

default: false

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

disabled 상태

readOnly 상태

isError 상태

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

Prop

rules

validate | required

필수 동의처럼 체크 여부가 true여야 하는 규칙은 validate로 연결하는 방식이 가장 명확합니다.

Props Table

Checkbox props 한눈에 보기

Checkbox에서 자주 사용하는 핵심 props와 context 연동 동작을 표로 정리했습니다.

Prop	Type	Default	Required	Description
`id`	`string`	`generated id`	Optional	직접 id를 주지 않으면 Field context id 또는 React useId 기반 id를 사용합니다.
`name`	`string`	`undefined`	Optional	단일 Checkbox에서는 선택적이며, CheckboxGroup 내부에서는 그룹의 name을 기본 상속합니다.
`checked`	`boolean`	`undefined`	Optional	controlled usage에서 현재 체크 상태를 외부 값으로 제어합니다.
`defaultChecked`	`boolean`	`undefined`	Optional	uncontrolled usage에서 초기 체크 상태를 지정할 때 사용합니다.
`value`	`string \| number \| readonly string[]`	`"on"`	Optional	폼 제출이나 그룹 제어에서 체크박스 항목 값을 구분할 때 사용합니다.
`disabled`	`boolean`	`false`	Optional	비활성 상태를 적용합니다. CheckboxGroup에 있으면 그룹의 disabled를 기본 상속합니다.
`readOnly`	`boolean`	`false`	Optional	포커스와 읽기는 허용하되 스페이스, 엔터, 클릭으로 값이 바뀌지 않게 막습니다.
`isError`	`boolean`	`false`	Optional	시각 에러 상태와 aria-invalid를 적용합니다. Field 또는 CheckboxGroup의 에러 상태와 함께 합쳐집니다.
`onChange`	`React.ChangeEventHandler<HTMLInputElement>`	`undefined`	Optional	체크 상태 변경 시 호출됩니다. controlled usage에서는 checked와 함께 사용합니다.
`aria-describedby`	`string`	`merged ids`	Optional	직접 전달한 값에 Field 설명/에러 메시지 id가 있으면 함께 병합됩니다.
`className`	`string`	`undefined`	Optional	루트 wrapper에 커스텀 클래스를 추가합니다.

CheckboxProps는 InputHTMLAttributes를 기반으로 하지만 type은 내부에서 항상 "checkbox"로 고정되고, readOnly는 커스텀 상호작용 제어 방식으로 처리됩니다. Field 또는 CheckboxGroup 안에서 사용할 때 일부 상태와 aria 값이 자동으로 병합됩니다.

Props Table

CheckboxGroup props 한눈에 보기

CheckboxGroup의 레이아웃과 공통 상태 전파 props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`children`	`React.ReactNode`	-	Required	보통 여러 Checkbox와 Field.Item 조합을 자식으로 배치합니다.
`name`	`string`	`undefined`	Optional	하위 Checkbox들이 공통으로 사용할 name 값을 제공합니다.
`direction`	`"row" \| "column"`	`"column"`	Optional	그룹 내부 체크박스 배치 방향을 지정합니다.
`disabled`	`boolean`	`false`	Optional	하위 Checkbox들이 기본적으로 상속할 disabled 상태를 제공합니다.
`readOnly`	`boolean`	`false`	Optional	하위 Checkbox들이 기본적으로 상속할 readOnly 상태를 제공합니다.
`isError`	`boolean`	`false`	Optional	그룹 단위 에러 상태를 지정합니다. Field의 에러 상태와 합쳐져 하위 Checkbox에 전달됩니다.
`aria-labelledby`	`string`	`merged ids`	Optional	직접 전달한 값에 Field label id가 있으면 함께 병합되어 group label로 사용됩니다.
`aria-describedby`	`string`	`merged ids`	Optional	직접 전달한 값에 Field 설명/에러 id가 있으면 함께 병합됩니다.
`className`	`string`	`undefined`	Optional	그룹 루트 wrapper에 커스텀 클래스를 추가합니다.

CheckboxGroupProps는 HTMLAttributes<HTMLDivElement>를 기반으로 하며 role은 내부에서 항상 "group"으로 고정됩니다. name, disabled, readOnly, isError는 context로 하위 Checkbox에 전달됩니다.

Props Table

RHFCheckbox props 한눈에 보기

RHFCheckbox에서 사용하는 RHF 제어 props와 Checkbox 상속 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와 실제 Checkbox에 동시에 반영되어 필드 업데이트와 상호작용을 막습니다.
`readOnly`	`boolean`	`false`	Optional	Checkbox로 전달되어 현재 값을 유지한 채 변경만 막습니다.
`isError`	`boolean`	`false`	Optional	RHF validation error와 별도로 추가 시각 에러 상태를 강제할 때 사용합니다.
`id / value / aria-describedby / className`	`Checkbox inherited props`	`inherited`	Optional	RHF가 직접 관리하지 않는 Checkbox props는 그대로 전달할 수 있습니다.

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