Checkbox

체크박스 컴포넌트는 선택/해제 상태를 나타내는 폼 요소입니다.

기본 사용법

체크박스 예제

체크된 상태 (비활성화)

import { Checkbox } from '@aift/ui/Checkbox';

export default function Preview() {
  return (
    <div className="space-y-4">
      <div className="flex items-center gap-2">
        <Checkbox value="checkbox-1" label="체크박스 예제" />
      </div>
      <div className="flex items-center gap-2">
        <Checkbox value="checkbox-2" label="체크된 상태 (비활성화)" checked disabled />
      </div>
    </div>
  );
}

import { Checkbox } from '@aift/ui/Checkbox';export default function Preview() {  return (    <div className="space-y-4">      <div className="flex items-center gap-2">        <Checkbox value="checkbox-1" label="체크박스 예제" />      </div>      <div className="flex items-center gap-2">        <Checkbox value="checkbox-2" label="체크된 상태 (비활성화)" checked disabled />      </div>    </div>  );}

Variant

outlined

fill

'use client';

import { Checkbox } from '@aift/ui/Checkbox';

export default function Variant() {
  return (
    <div className="flex flex-col space-y-4 gap-4">
      <Checkbox value="checkbox-0" checked={false} label="outlined" />
      <Checkbox value="checkbox-2" checked={true} label="fill" variant='fill'/>
    </div>
  );
}

'use client';import { Checkbox } from '@aift/ui/Checkbox';export default function Variant() {  return (    <div className="flex flex-col space-y-4 gap-4">      <Checkbox value="checkbox-0" checked={false} label="outlined" />      <Checkbox value="checkbox-2" checked={true} label="fill" variant='fill'/>    </div>  );}

State

unchecked

checked

indeterminate

'use client';

import { Checkbox } from '@aift/ui/Checkbox';

export default function State() {
  return (
    <div className="flex flex-col space-y-4 gap-4">
      <Checkbox value="checkbox-0" checked={false} label="unchecked"/>
      <Checkbox value="checkbox-2" checked={true} label="checked"/>
      <Checkbox value="checkbox-1" checked="indeterminate" label="indeterminate"/>
    </div>
  );
}

'use client';import { Checkbox } from '@aift/ui/Checkbox';export default function State() {  return (    <div className="flex flex-col space-y-4 gap-4">      <Checkbox value="checkbox-0" checked={false} label="unchecked"/>      <Checkbox value="checkbox-2" checked={true} label="checked"/>      <Checkbox value="checkbox-1" checked="indeterminate" label="indeterminate"/>    </div>  );}

React Hook Form

'use client';

import { Checkbox, CheckboxGroup } from '@aift/ui/Checkbox';
import { useController, useForm } from 'react-hook-form';
import { useState } from 'react';
import { Button } from '@aift/ui/Button';

interface FormData {
  terms: boolean;
  privacy: boolean;
  marketing: boolean;
}

export default function ReactHookForm() {
  const { reset, handleSubmit, formState: { errors, isSubmitting }, control } = useForm<FormData>({
    mode: 'onSubmit',
    reValidateMode: 'onChange',
    defaultValues: {
      terms: false,
      privacy: false,
      marketing: false,
    },
  });

  const { field: termsField } = useController({
    name: 'terms',
    control: control,
  });

  const { field: privacyField } = useController({
    name: 'privacy',
    control: control,
  });

  const { field: marketingField } = useController({
    name: 'marketing',
    control: control,
  });

  const [errorText, setErrorText] = useState<string>('');

  const onSubmit = (data: FormData) => {

    if (!data.marketing && !data.terms && !data.privacy) {
      setErrorText('약관 동의를 해주세요.');
      return;
    }

    if (!data.terms || !data.privacy) {
      setErrorText('필수 항목에 동의를 해주세요.');
      return;
    }

    setErrorText('');
  };

  const handleReset = () => {
    setErrorText('');
    reset();
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
      <CheckboxGroup
        legend="약관 동의"
        required
        errorText={errorText}
        name="agreements"
      >
        <Checkbox 
          value="terms" 
          label="이용약관 동의 (필수)" 
          checked={termsField.value}
          onCheckedChange={(checked) => termsField.onChange(checked)}
          onBlur={termsField.onBlur}
          name={termsField.name}
          inputRef={termsField.ref}
        />
        <Checkbox 
          value="privacy" 
          label="개인정보 처리방침 동의 (필수)" 
          checked={privacyField.value}
          onCheckedChange={(checked) => privacyField.onChange(checked)}
          onBlur={privacyField.onBlur}
          name={privacyField.name}
          inputRef={privacyField.ref}
        />
        <Checkbox 
          value="marketing" 
          label="마케팅 수신 동의 (선택)" 
          checked={marketingField.value}
          onCheckedChange={(checked) => marketingField.onChange(checked)}
          onBlur={marketingField.onBlur}
          name={marketingField.name}
          inputRef={marketingField.ref}
        />
      </CheckboxGroup>
      <div className="flex gap-2 mt-4">
        <Button type="button" variant="outlined" onClick={handleReset}>초기화</Button>
        <Button type="submit" disabled={isSubmitting} variant="contained" color="primary">제출</Button>
      </div>
    </form>
  );
}

'use client';import { Checkbox, CheckboxGroup } from '@aift/ui/Checkbox';import { useController, useForm } from 'react-hook-form';import { useState } from 'react';import { Button } from '@aift/ui/Button';interface FormData {  terms: boolean;  privacy: boolean;  marketing: boolean;}export default function ReactHookForm() {  const { reset, handleSubmit, formState: { errors, isSubmitting }, control } = useForm<FormData>({    mode: 'onSubmit',    reValidateMode: 'onChange',    defaultValues: {      terms: false,      privacy: false,      marketing: false,    },  });  const { field: termsField } = useController({    name: 'terms',    control: control,  });  const { field: privacyField } = useController({    name: 'privacy',    control: control,  });  const { field: marketingField } = useController({    name: 'marketing',    control: control,  });  const [errorText, setErrorText] = useState<string>('');  const onSubmit = (data: FormData) => {    if (!data.marketing && !data.terms && !data.privacy) {      setErrorText('약관 동의를 해주세요.');      return;    }    if (!data.terms || !data.privacy) {      setErrorText('필수 항목에 동의를 해주세요.');      return;    }    setErrorText('');  };  const handleReset = () => {    setErrorText('');    reset();  }  return (    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">      <CheckboxGroup        legend="약관 동의"        required        errorText={errorText}        name="agreements"      >        <Checkbox           value="terms"           label="이용약관 동의 (필수)"           checked={termsField.value}          onCheckedChange={(checked) => termsField.onChange(checked)}          onBlur={termsField.onBlur}          name={termsField.name}          inputRef={termsField.ref}        />        <Checkbox           value="privacy"           label="개인정보 처리방침 동의 (필수)"           checked={privacyField.value}          onCheckedChange={(checked) => privacyField.onChange(checked)}          onBlur={privacyField.onBlur}          name={privacyField.name}          inputRef={privacyField.ref}        />        <Checkbox           value="marketing"           label="마케팅 수신 동의 (선택)"           checked={marketingField.value}          onCheckedChange={(checked) => marketingField.onChange(checked)}          onBlur={marketingField.onBlur}          name={marketingField.name}          inputRef={marketingField.ref}        />      </CheckboxGroup>      <div className="flex gap-2 mt-4">        <Button type="button" variant="outlined" onClick={handleReset}>초기화</Button>        <Button type="submit" disabled={isSubmitting} variant="contained" color="primary">제출</Button>      </div>    </form>  );}

Hooks

useCheckboxGroup

사과

바나나

오렌지

선택된 값: apple

전체 선택: 아니오

일부 선택(부분 선택): 예

'use client'

import { Checkbox, CheckboxGroup, useCheckboxGroup } from '@aift/ui/Checkbox'

function GroupState() {
  const group = useCheckboxGroup()

  if (!group) return null

  return (
    <div className="mt-2 text-xs text-neutral-60 space-y-1">
      <div>선택된 값: {group.value.length ? group.value.join(', ') : '없음'}</div>
      <div>전체 선택: {group.isAllSelected ? '예' : '아니오'}</div>
      <div>일부 선택(부분 선택): {group.isIndeterminate ? '예' : '아니오'}</div>
    </div>
  )
}

export default function Hooks() {
  return (
    <div className="space-y-2">
      <CheckboxGroup
        name="checkbox-group-hooks"
        defaultValue={['apple']}
      >
        <Checkbox value="apple" label="사과" />
        <Checkbox value="banana" label="바나나" />
        <Checkbox value="orange" label="오렌지" />
        <GroupState />
      </CheckboxGroup>
    </div>
  )
}

'use client'import { Checkbox, CheckboxGroup, useCheckboxGroup } from '@aift/ui/Checkbox'function GroupState() {  const group = useCheckboxGroup()  if (!group) return null  return (    <div className="mt-2 text-xs text-neutral-60 space-y-1">      <div>선택된 값: {group.value.length ? group.value.join(', ') : '없음'}</div>      <div>전체 선택: {group.isAllSelected ? '예' : '아니오'}</div>      <div>일부 선택(부분 선택): {group.isIndeterminate ? '예' : '아니오'}</div>    </div>  )}export default function Hooks() {  return (    <div className="space-y-2">      <CheckboxGroup        name="checkbox-group-hooks"        defaultValue={['apple']}      >        <Checkbox value="apple" label="사과" />        <Checkbox value="banana" label="바나나" />        <Checkbox value="orange" label="오렌지" />        <GroupState />      </CheckboxGroup>    </div>  )}

Prop	Type	Default	Description
value	`(string \| number)[]`	-	선택된 값들의 배열
isAllSelected	`boolean`	-	전체 선택 여부
isIndeterminate	`boolean`	-	일부 선택(부분 선택) 여부

Props

`Checkbox`

Prop	Type	Default	Description
checked	`boolean \| 'indeterminate'`	-	체크 상태 (controlled 모드)
defaultChecked	`boolean \| 'indeterminate'`	-	기본 체크 상태 (uncontrolled 모드)
onCheckedChange	`(checked: boolean \| 'indeterminate') => void`	-	체크 상태 변경 핸들러
variant	`'fill' \| 'outlined'`	`'outlined'`	체크박스 변형
color	`'primary' \| 'positive' \| 'cautionary' \| 'destructive' \| 'info'`	`'primary'`	체크박스 색상
label	`React.ReactNode`	-	체크박스 라벨
disabled	`boolean`	`false`	비활성화 여부
id	`string`	-	체크박스 ID
name	`string`	-	체크박스 name 속성 (폼 제출 시 사용)
value	`string \| number`	-	체크박스 value 속성 (폼 제출 시 사용)
inputRef	`Ref<HTMLInputElement>`	-	input 요소의 ref (react-hook-form 등에서 사용)
className	`string`	-	추가 클래스명

`CheckboxGroup`

Prop	Type	Default	Description
children	`React.ReactNode`	필수	체크박스 옵션 목록
name	`string`	-	그룹 이름 (fieldset의 name 속성)
legend	`string`	-	그룹 제목 (legend)
disabled	`boolean`	`false`	전체 그룹 비활성화 여부
variant	`'fill' \| 'outlined'`	`'outlined'`	체크박스 기본 variant (개별 옵션에 variant가 없을 때 사용)
className	`string`	-	추가 클래스명
gap	`'sm' \| 'md' \| 'lg' \| number`	`'md'`	옵션 간 간격
orientation	`'vertical' \| 'horizontal'`	`'vertical'`	레이아웃 방향
helperText	`string`	-	도움말 텍스트
errorText	`string`	-	에러 텍스트
warnText	`string`	-	경고 텍스트
required	`boolean`	-	필수 여부

Checkbox

On this page