Checkbox

선택 항목을 체크하는 체크박스 컴포넌트입니다.

개요

Checkbox는 하나 이상의 옵션을 선택할 수 있는 컴포넌트입니다. iCignal 브랜드 컬러를 적용하여 데이터 분석 설정에 최적화되어 있습니다.

주요 특징:

단일 / 그룹 체크박스
Indeterminate 상태
3가지 Size (sm, md, lg)
Label 지원
iCignal Blue Checked (#2196f3)

사용 사례:

리포트 옵션 선택
필터 조건 설정
데이터 필드 선택
기능 활성화 설정

설치


npx @vortex/cli add checkbox --package icignal

기본 사용법


import { Checkbox } from "@vortex/ui-icignal";
import "@vortex/ui-icignal/theme";
 
export default function Example() {
  return (
    <Checkbox>
      <label>리포트에 포함</label>
    </Checkbox>
  );
}

Variants (변형)

단일 체크박스


<Checkbox checked={checked} onCheckedChange={setChecked}>
  매출 데이터 포함
</Checkbox>

체크박스 그룹


export default function CheckboxGroup() {
  const [metrics, setMetrics] = useState([]);
 
  const toggleMetric = (metric) => {
    if (metrics.includes(metric)) {
      setMetrics(metrics.filter((m) => m !== metric));
    } else {
      setMetrics([...metrics, metric]);
    }
  };
 
  return (
    <div className="space-y-sm">
      <Checkbox
        checked={metrics.includes("users")}
        onCheckedChange={() => toggleMetric("users")}
      >
        활성 사용자
      </Checkbox>
      <Checkbox
        checked={metrics.includes("sessions")}
        onCheckedChange={() => toggleMetric("sessions")}
      >
        세션 수
      </Checkbox>
      <Checkbox
        checked={metrics.includes("conversion")}
        onCheckedChange={() => toggleMetric("conversion")}
      >
        전환율
      </Checkbox>
    </div>
  );
}

Indeterminate 상태


<Checkbox checked="indeterminate" onCheckedChange={handleChange}>
  전체 선택 (일부 선택됨)
</Checkbox>

Sizes (크기)


<Checkbox size="sm">Small</Checkbox>
<Checkbox size="md">Medium</Checkbox>
<Checkbox size="lg">Large</Checkbox>

🆕 iCignal 브랜딩

브랜드 컬러

iCignal Checkbox 컴포넌트는 다음 브랜드 컬러를 사용합니다:

Checked State: iCignal Blue #2196f3
Hover State: Light Blue
Indeterminate: iCignal Blue with dash

iCignal 특화 사용 가이드

Report Builder:


// 리포트 데이터 필드 선택
export default function ReportFields() {
  const [fields, setFields] = useState(["date", "revenue"]);
 
  const toggleField = (field) => {
    if (fields.includes(field)) {
      setFields(fields.filter((f) => f !== field));
    } else {
      setFields([...fields, field]);
    }
  };
 
  return (
    <div className="space-y-sm">
      <h4 className="font-medium">리포트 포함 필드</h4>
      <Checkbox
        checked={fields.includes("date")}
        onCheckedChange={() => toggleField("date")}
      >
        날짜
      </Checkbox>
      <Checkbox
        checked={fields.includes("campaign")}
        onCheckedChange={() => toggleField("campaign")}
      >
        캠페인명
      </Checkbox>
      <Checkbox
        checked={fields.includes("impressions")}
        onCheckedChange={() => toggleField("impressions")}
      >
        노출수
      </Checkbox>
      <Checkbox
        checked={fields.includes("clicks")}
        onCheckedChange={() => toggleField("clicks")}
      >
        클릭수
      </Checkbox>
      <Checkbox
        checked={fields.includes("revenue")}
        onCheckedChange={() => toggleField("revenue")}
      >
        매출
      </Checkbox>
    </div>
  );
}

Dashboard Filters:


// 대시보드 필터 설정
export default function DashboardFilters() {
  const [filters, setFilters] = useState(["paid", "organic"]);
 
  return (
    <div className="space-y-md">
      <div>
        <h4 className="font-medium mb-sm">트래픽 소스</h4>
        <div className="space-y-sm">
          <Checkbox
            checked={filters.includes("paid")}
            onCheckedChange={(checked) => {
              setFilters(
                checked
                  ? [...filters, "paid"]
                  : filters.filter((f) => f !== "paid")
              );
            }}
          >
            유료 광고
          </Checkbox>
          <Checkbox
            checked={filters.includes("organic")}
            onCheckedChange={(checked) => {
              setFilters(
                checked
                  ? [...filters, "organic"]
                  : filters.filter((f) => f !== "organic")
              );
            }}
          >
            자연 검색
          </Checkbox>
          <Checkbox
            checked={filters.includes("social")}
            onCheckedChange={(checked) => {
              setFilters(
                checked
                  ? [...filters, "social"]
                  : filters.filter((f) => f !== "social")
              );
            }}
          >
            소셜 미디어
          </Checkbox>
        </div>
      </div>
    </div>
  );
}

Data Export Settings:


// 데이터 내보내기 설정
<div className="space-y-sm">
  <h4 className="font-medium">내보내기 옵션</h4>
  <Checkbox defaultChecked>헤더 포함</Checkbox>
  <Checkbox defaultChecked>날짜 포맷 변환</Checkbox>
  <Checkbox>빈 값 제외</Checkbox>
  <Checkbox>중복 제거</Checkbox>
</div>

🆕 Foundation과의 차이점

항목	Foundation	iCignal
Checked Color	Neutral Blue	iCignal Blue (#2196f3)
사용 맥락	범용 웹 애플리케이션	Analytics Dashboard & Reports
테마	기본 Vortex 테마	iCignal 브랜드 테마
Import	`@vortex/ui-foundation`	`@vortex/ui-icignal` + `theme`

Props API

Prop	Type	Default	Description
checked	boolean \| ‘indeterminate’	false	체크 상태
defaultChecked	boolean	false	기본 체크 상태
disabled	boolean	false	비활성화 상태
size	’sm’ \| ‘md’ \| ‘lg'	'md’	크기
onCheckedChange	(checked) => void	-	상태 변경 핸들러
className	string	-	추가 CSS 클래스
children	ReactNode	-	Label 내용

접근성

Checkbox 컴포넌트는 WCAG 2.1 AA 기준을 준수합니다.

ARIA 속성:

role="checkbox" (자동 적용)
aria-checked (체크 상태)
aria-label (Label 없을 경우 필수)

키보드 네비게이션:

Space: 체크/해제
Tab: 다음 요소로 이동

예제

예제 1: 리포트 필드 선택 (전체 선택 포함)


import { Checkbox } from "@vortex/ui-icignal";
 
export default function ReportFieldSelector() {
  const allFields = [
    "date",
    "campaign",
    "impressions",
    "clicks",
    "ctr",
    "cost",
    "revenue",
    "roi",
  ];
  const [selectedFields, setSelectedFields] = useState(["date", "revenue"]);
 
  const allSelected = selectedFields.length === allFields.length;
  const someSelected =
    selectedFields.length > 0 && selectedFields.length < allFields.length;
 
  const handleSelectAll = () => {
    if (allSelected) {
      setSelectedFields([]);
    } else {
      setSelectedFields(allFields);
    }
  };
 
  const toggleField = (field) => {
    if (selectedFields.includes(field)) {
      setSelectedFields(selectedFields.filter((f) => f !== field));
    } else {
      setSelectedFields([...selectedFields, field]);
    }
  };
 
  return (
    <div className="space-y-md">
      <Checkbox
        checked={allSelected ? true : someSelected ? "indeterminate" : false}
        onCheckedChange={handleSelectAll}
      >
        <span className="font-medium">전체 선택</span>
      </Checkbox>
      <div className="pl-lg space-y-sm">
        {allFields.map((field) => (
          <Checkbox
            key={field}
            checked={selectedFields.includes(field)}
            onCheckedChange={() => toggleField(field)}
          >
            {field}
          </Checkbox>
        ))}
      </div>
      <p className="text-sm text-gray-600">
        {selectedFields.length}개 필드 선택됨
      </p>
    </div>
  );
}

예제 2: 대시보드 위젯 설정


import { Checkbox } from "@vortex/ui-icignal";
 
export default function DashboardWidgets() {
  const [widgets, setWidgets] = useState({
    overview: true,
    traffic: true,
    conversion: false,
    revenue: true,
    goals: false,
  });
 
  const toggleWidget = (widget) => {
    setWidgets({ ...widgets, [widget]: !widgets[widget] });
  };
 
  return (
    <div className="space-y-sm">
      <h4 className="font-medium">대시보드 위젯</h4>
      <Checkbox
        checked={widgets.overview}
        onCheckedChange={() => toggleWidget("overview")}
      >
        개요 위젯
      </Checkbox>
      <Checkbox
        checked={widgets.traffic}
        onCheckedChange={() => toggleWidget("traffic")}
      >
        트래픽 분석
      </Checkbox>
      <Checkbox
        checked={widgets.conversion}
        onCheckedChange={() => toggleWidget("conversion")}
      >
        전환 퍼널
      </Checkbox>
      <Checkbox
        checked={widgets.revenue}
        onCheckedChange={() => toggleWidget("revenue")}
      >
        매출 현황
      </Checkbox>
      <Checkbox
        checked={widgets.goals}
        onCheckedChange={() => toggleWidget("goals")}
      >
        목표 달성률
      </Checkbox>
    </div>
  );
}