Checkbox

사용자가 여러 옵션 중에서 하나 이상을 선택할 수 있는 체크박스 컴포넌트입니다. 라이트/다크 테마를 자동으로 지원합니다.

기본 사용법

import { Checkbox } from 'react-common-components-library';

function CheckboxExample() {
  return (
    <Checkbox>이용약관에 동의합니다</Checkbox>
  );
}

이용약관에 동의합니다

다양한 상태

체크박스는 다양한 상태를 지원합니다:

import { Checkbox } from 'react-common-components-library';
import { useState } from 'react';

function CheckboxStatesExample() {
  const [isChecked, setIsChecked] = useState(false);
  
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
      {/* 기본 상태 */}
      <Checkbox>기본 체크박스</Checkbox>
      
      {/* 체크된 상태 */}
      <Checkbox defaultChecked>체크된 체크박스</Checkbox>
      
      {/* 비활성화 상태 */}
      <Checkbox isDisabled>비활성화 체크박스</Checkbox>
      
      {/* 비활성화 + 체크된 상태 */}
      <Checkbox isDisabled defaultChecked>비활성화 + 체크된 체크박스</Checkbox>
      
      {/* 불확실한 상태 */}
      <Checkbox isIndeterminate>불확실한 체크박스</Checkbox>
      
      {/* 제어 컴포넌트 */}
      <Checkbox 
        isChecked={isChecked} 
        onChange={(e) => setIsChecked(e.target.checked)}
      >
        클릭하여 상태 변경 ({isChecked ? '체크됨' : '체크되지 않음'})
      </Checkbox>
    </div>
  );
}

체크박스 그룹

여러 체크박스를 그룹으로 관리할 수 있습니다:

import { CheckboxGroup, Checkbox } from 'react-common-components-library';
import { useState } from 'react';

function CheckboxGroupExample() {
  const [value, setValue] = useState(['apple']);
  
  return (
    <CheckboxGroup 
      value={value}
      onChange={(newValue) => setValue(newValue)}
    >
      <Checkbox value="apple">사과</Checkbox>
      <Checkbox value="banana">바나나</Checkbox>
      <Checkbox value="orange">오렌지</Checkbox>
    </CheckboxGroup>
  );
}

사과바나나오렌지

선택된 항목: apple

부모-자식 관계 체크박스

부모 체크박스와 자식 체크박스 간의 관계를 구현할 수 있습니다:

import { Checkbox } from 'react-common-components-library';
import { useState, useEffect } from 'react';

function ParentChildCheckboxExample() {
  const [parentChecked, setParentChecked] = useState(false);
  const [parentIndeterminate, setParentIndeterminate] = useState(false);
  
  const [child1, setChild1] = useState(false);
  const [child2, setChild2] = useState(false);
  const [child3, setChild3] = useState(false);
  
  // 자식 체크박스 상태에 따라 부모 체크박스 상태 업데이트
  useEffect(() => {
    const allChecked = child1 && child2 && child3;
    const someChecked = child1 || child2 || child3;
    
    setParentChecked(allChecked);
    setParentIndeterminate(someChecked && !allChecked);
  }, [child1, child2, child3]);
  
  // 부모 체크박스 변경 시 모든 자식 체크박스 상태 업데이트
  const handleParentChange = (e) => {
    const isChecked = e.target.checked;
    setParentChecked(isChecked);
    setParentIndeterminate(false);
    setChild1(isChecked);
    setChild2(isChecked);
    setChild3(isChecked);
  };
  
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
      <Checkbox 
        isChecked={parentChecked}
        isIndeterminate={parentIndeterminate}
        onChange={handleParentChange}
      >
        모든 항목 선택
      </Checkbox>
      
      <div style={{ marginLeft: '24px', display: 'flex', flexDirection: 'column', gap: '8px' }}>
        <Checkbox 
          isChecked={child1}
          onChange={(e) => setChild1(e.target.checked)}
        >
          항목 1
        </Checkbox>
        
        <Checkbox 
          isChecked={child2}
          onChange={(e) => setChild2(e.target.checked)}
        >
          항목 2
        </Checkbox>
        
        <Checkbox 
          isChecked={child3}
          onChange={(e) => setChild3(e.target.checked)}
        >
          항목 3
        </Checkbox>
      </div>
    </div>
  );
}

모든 항목 선택

항목 1항목 2항목 3

커스텀 스타일

체크박스의 스타일을 커스터마이징할 수 있습니다:

import { Checkbox } from 'react-common-components-library';

function CustomCheckboxExample() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
      <Checkbox 
        colorScheme="red"
        size="lg"
      >
        빨간색 큰 체크박스
      </Checkbox>
      
      <Checkbox 
        colorScheme="green"
        size="md"
      >
        녹색 중간 체크박스
      </Checkbox>
      
      <Checkbox 
        colorScheme="purple"
        size="sm"
      >
        보라색 작은 체크박스
      </Checkbox>
    </div>
  );
}

빨간색 큰 체크박스

녹색 중간 체크박스

보라색 작은 체크박스

API 참조

Checkbox Props

속성	타입	기본값	설명
children	ReactNode	-	체크박스 레이블
isChecked	boolean	-	체크박스의 체크 상태 (제어 컴포넌트)
defaultChecked	boolean	false	초기 체크 상태 (비제어 컴포넌트)
isIndeterminate	boolean	false	불확실한 상태 표시 여부
isDisabled	boolean	false	체크박스 비활성화 여부
isRequired	boolean	false	필수 입력 여부
isInvalid	boolean	false	유효하지 않은 상태 표시 여부
value	string | number	-	체크박스 값 (CheckboxGroup에서 사용)
name	string	-	체크박스 이름 (폼 제출 시 사용)
onChange	(event: ChangeEvent<HTMLInputElement>) => void	-	체크 상태 변경 시 호출되는 함수
onBlur	(event: FocusEvent<HTMLInputElement>) => void	-	포커스를 잃을 때 호출되는 함수
onFocus	(event: FocusEvent<HTMLInputElement>) => void	-	포커스를 얻을 때 호출되는 함수
colorScheme	string	'blue'	체크박스 색상 스키마