HomeGitHub
Next UI Components Guide
Project Information

Radio / RadioGroup / RHFRadio

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

Radio

Radio / controlled usage

Radio는 checked와 onChange를 외부 상태로 관리하는 controlled usage를 기준으로 정리한 단일 선택 컴포넌트입니다. value로 각 선택 항목을 구분합니다.

Prop

checked | value | name | onChange

boolean | string | React.ChangeEventHandler<HTMLInputElement>

여러 Radio가 같은 name을 공유하고, 현재 선택된 value를 기준으로 checked를 계산합니다. controlled usage에서는 onChange로 다음 선택값을 외부 상태에 반영합니다.

Prop

RadioGroup | direction

name | "row" | "column"

RadioGroup은 단일 선택 항목을 한 그룹으로 묶고, direction으로 row/column 배치를 바꿀 수 있습니다.

Prop

disabled | readOnly | isError

boolean
default: false

disabled는 상호작용을 막고, readOnly는 현재 선택 상태를 유지한 채 변경만 막습니다. isError는 상태를 강조할 때 사용합니다.

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

RHFRadio / 폼 연동

RHFRadio는 같은 name 아래 여러 옵션을 두고, 선택된 value를 React Hook Form 필드와 연결한 래퍼 컴포넌트입니다.

Prop

Radio props 확장 + RHFComponentProps

RHFComponentProps<TFormValues, TFieldName, RadioProps, RHFCheckedInputManagedProps | "value"> & { value: NonNullable<RadioProps["value"]>; }

RHFRadio는 Radio props를 기반으로 하고, checked/defaultChecked/defaultValue/name/onBlur/onChange는 RHF가 관리합니다. 각 옵션은 자신의 value를 필수로 전달하고, 같은 name을 공유한 여러 RHFRadio가 하나의 RHF 필드를 함께 사용합니다. 초기 선택값은 보통 useForm의 defaultValues로 둡니다.

Prop

shouldUnregister

boolean
default: false

shouldUnregister는 라디오 그룹 전체가 조건부 렌더링으로 사라질 때 선택값을 폼 상태에서 제거하고 싶을 때 사용합니다.

라디오 그룹이 보이는 상태에서 선택값을 유지합니다.

Prop

disabled | readOnly | isError

boolean
default: false

RHFRadio도 Radio 상태 props를 그대로 상속합니다. disabled는 입력 상호작용을 막고, readOnly는 현재 선택 상태를 유지한 채 변경만 막습니다. isError는 RHF 검증 상태에 시각 에러 상태를 추가할 때 사용할 수 있습니다.

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

rules

required | validate

선택이 필수인 라디오 그룹은 required 규칙으로 간단하게 검증할 수 있습니다.

Props Table

Radio props 한눈에 보기

Radio에서 자주 사용하는 핵심 props와 그룹 상속 동작을 표로 정리했습니다.

PropTypeDefaultRequiredDescription
idstringgenerated idOptional직접 id를 주지 않으면 Field context id 또는 React useId 기반 id를 사용합니다.
namestringundefinedOptional단일 Radio에서는 선택적이며, RadioGroup 내부에서는 그룹의 name을 기본 상속합니다.
valuestring | number | readonly string[]"on" (native default)Optional각 선택 항목을 구분하는 값입니다. 라디오 그룹에서는 명시적으로 지정하는 것이 일반적입니다.
checkedbooleanundefinedOptionalcontrolled usage에서 현재 선택 여부를 외부 값으로 계산해 전달합니다.
defaultCheckedbooleanundefinedOptionaluncontrolled usage에서 초기 선택 상태를 지정할 때 사용합니다.
disabledbooleanfalseOptional비활성 상태를 적용합니다. RadioGroup에 있으면 그룹의 disabled를 기본 상속합니다.
readOnlybooleanfalseOptional포커스와 읽기는 허용하되 스페이스, 엔터, 클릭으로 선택이 바뀌지 않게 막습니다.
isErrorbooleanfalseOptional시각 에러 상태를 적용합니다. RadioGroup 또는 Field의 에러 상태와 함께 합쳐집니다.
onChangeReact.ChangeEventHandler<HTMLInputElement>undefinedOptional선택 상태 변경 시 호출됩니다. controlled usage에서는 외부 상태 업데이트와 함께 사용합니다.
aria-describedbystringmerged idsOptional직접 전달한 값에 Field 설명/에러 메시지 id가 있으면 함께 병합됩니다.
classNamestringundefinedOptional루트 wrapper에 커스텀 클래스를 추가합니다.
RadioProps는 InputHTMLAttributes를 기반으로 하지만 type은 내부에서 항상 "radio"로 고정됩니다. Field 또는 RadioGroup 안에서 사용할 때 일부 상태와 aria 값이 자동으로 병합됩니다.
Props Table

RadioGroup props 한눈에 보기

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

PropTypeDefaultRequiredDescription
childrenReact.ReactNode-Required보통 여러 Radio와 Field.Item 조합을 자식으로 배치합니다.
namestringundefinedOptional하위 Radio들이 공통으로 사용할 name 값을 제공합니다.
direction"row" | "column""column"Optional그룹 내부 라디오 배치 방향을 지정합니다.
disabledbooleanfalseOptional하위 Radio들이 기본적으로 상속할 disabled 상태를 제공합니다.
readOnlybooleanfalseOptional하위 Radio들이 기본적으로 상속할 readOnly 상태를 제공합니다.
isErrorbooleanfalseOptional그룹 단위 에러 상태를 지정합니다. Field의 에러 상태와 합쳐져 하위 Radio에 전달됩니다.
aria-labelledbystringmerged idsOptional직접 전달한 값에 Field label id가 있으면 함께 병합되어 group label로 사용됩니다.
aria-describedbystringmerged idsOptional직접 전달한 값에 Field 설명/에러 id가 있으면 함께 병합됩니다.
classNamestringundefinedOptional그룹 루트 wrapper에 커스텀 클래스를 추가합니다.
RadioGroupProps는 HTMLAttributes<HTMLDivElement>를 기반으로 하며 role은 내부에서 항상 "radiogroup"로 고정됩니다. name, disabled, readOnly, isError는 context로 하위 Radio에 전달됩니다.
Props Table

RHFRadio props 한눈에 보기

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

PropTypeDefaultRequiredDescription
nameFieldPath<TFormValues>-RequiredReact Hook Form 필드 경로입니다.
controlControl<TFormValues>-RequireduseForm에서 받은 control 객체를 전달합니다.
valueNonNullable<RadioProps['value']>-Required각 RHFRadio 옵션이 대표하는 실제 선택값입니다. 같은 name 아래 여러 옵션이 이 값으로 구분됩니다.
rulesUseControllerProps['rules']undefinedOptionalrequired 같은 검증 규칙을 useController 규격으로 전달합니다.
defaultValueRadioProps['value']undefinedOptional필요할 때만 사용하며, 일반적으로는 useForm의 defaultValues를 우선 사용합니다.
shouldUnregisterbooleanfalseOptional조건부 렌더링으로 라디오 그룹이 사라질 때 RHF 상태에서도 값을 제거할지 결정합니다.
disabledbooleanfalseOptionaluseController와 실제 Radio에 동시에 반영되어 필드 업데이트와 상호작용을 막습니다.
readOnlybooleanfalseOptionalRadio로 전달되어 현재 선택을 유지한 채 변경만 막습니다.
isErrorbooleanfalseOptionalRHF validation error와 별도로 추가 시각 에러 상태를 강제할 때 사용합니다.
id / aria-describedby / classNameRadio inherited propsinheritedOptionalRHF가 직접 관리하지 않는 Radio props는 그대로 전달할 수 있습니다.
RHFRadioProps는 RHFComponentProps<TFormValues, TFieldName, RadioProps, RHFCheckedInputManagedProps | "value">와 필수 value prop 조합입니다. 그래서 checked, defaultChecked, defaultValue, name, onBlur, onChange는 RHF가 관리하고, 각 옵션은 자신의 value를 반드시 전달해야 합니다.