Checkbox | CoUI
LogoCoUI

Checkbox

체크박스 컴포넌트 (불확정 상태 지원)

Checkbox#

하나 이상의 항목을 선택할 수 있는 체크박스 컴포넌트입니다. 불확정(indeterminate) 상태를 지원합니다.

Live Preview#

default
Web
Flutter
Loading Flutter... 
class CheckboxDefaultExample extends StatefulComponent {
  const CheckboxDefaultExample({super.key});

  @override
  State<CheckboxDefaultExample> createState() => _CheckboxDefaultExampleState();
}

class _CheckboxDefaultExampleState extends State<CheckboxDefaultExample> {
  CoreCheckboxState _state = CoreCheckboxState.unchecked;

  @override
  Component build(BuildContext context) {
    return CoCheckbox(
      state: _state,
      label: 'Accept terms',
      onChanged: (value) => setState(() => _state = value),
    );
  }
}
class CheckboxDefaultExample extends StatefulWidget {
  const CheckboxDefaultExample({super.key});

  @override
  State<CheckboxDefaultExample> createState() => _CheckboxDefaultExampleState();
}

class _CheckboxDefaultExampleState extends State<CheckboxDefaultExample> {
  CoreCheckboxState _state = CoreCheckboxState.unchecked;

  @override
  Widget build(BuildContext context) {
    return CoCheckbox(
      state: _state,
      label: 'Accept terms',
      onChanged: (value) => setState(() => _state = value),
    );
  }
}
checked
Web
Flutter
Loading Flutter... 
class CheckboxCheckedExample extends StatefulComponent {
  const CheckboxCheckedExample({super.key});

  @override
  State<CheckboxCheckedExample> createState() => _CheckboxCheckedExampleState();
}

class _CheckboxCheckedExampleState extends State<CheckboxCheckedExample> {
  CoreCheckboxState _state = CoreCheckboxState.checked;

  @override
  Component build(BuildContext context) {
    return CoCheckbox(
      state: _state,
      label: 'Checked',
      onChanged: (value) => setState(() => _state = value),
    );
  }
}
class CheckboxCheckedExample extends StatefulWidget {
  const CheckboxCheckedExample({super.key});

  @override
  State<CheckboxCheckedExample> createState() => _CheckboxCheckedExampleState();
}

class _CheckboxCheckedExampleState extends State<CheckboxCheckedExample> {
  CoreCheckboxState _state = CoreCheckboxState.checked;

  @override
  Widget build(BuildContext context) {
    return CoCheckbox(
      state: _state,
      label: 'Checked',
      onChanged: (value) => setState(() => _state = value),
    );
  }
}
indeterminate
Web
Flutter
Loading Flutter... 
class CheckboxIndeterminateExample extends StatefulComponent {
  const CheckboxIndeterminateExample({super.key});

  @override
  State<CheckboxIndeterminateExample> createState() => _CheckboxIndeterminateExampleState();
}

class _CheckboxIndeterminateExampleState extends State<CheckboxIndeterminateExample> {
  CoreCheckboxState _state = CoreCheckboxState.indeterminate;

  @override
  Component build(BuildContext context) {
    return CoCheckbox(
      state: _state,
      label: 'Indeterminate',
      tristate: true,
      onChanged: (value) => setState(() => _state = value),
    );
  }
}
class CheckboxIndeterminateExample extends StatefulWidget {
  const CheckboxIndeterminateExample({super.key});

  @override
  State<CheckboxIndeterminateExample> createState() => _CheckboxIndeterminateExampleState();
}

class _CheckboxIndeterminateExampleState extends State<CheckboxIndeterminateExample> {
  CoreCheckboxState _state = CoreCheckboxState.indeterminate;

  @override
  Widget build(BuildContext context) {
    return CoCheckbox(
      state: _state,
      label: 'Indeterminate',
      tristate: true,
      onChanged: (value) => setState(() => _state = value),
    );
  }
}
disabled
Web
Flutter
Loading Flutter... 
class CheckboxDisabledExample extends StatefulComponent {
  const CheckboxDisabledExample({super.key});

  @override
  State<CheckboxDisabledExample> createState() => _CheckboxDisabledExampleState();
}

class _CheckboxDisabledExampleState extends State<CheckboxDisabledExample> {
  CoreCheckboxState _state = CoreCheckboxState.unchecked;

  @override
  Component build(BuildContext context) {
    return CoCheckbox(
      state: _state,
      label: 'Disabled',
      enabled: false,
      onChanged: (value) => setState(() => _state = value),
    );
  }
}
class CheckboxDisabledExample extends StatefulWidget {
  const CheckboxDisabledExample({super.key});

  @override
  State<CheckboxDisabledExample> createState() => _CheckboxDisabledExampleState();
}

class _CheckboxDisabledExampleState extends State<CheckboxDisabledExample> {
  CoreCheckboxState _state = CoreCheckboxState.unchecked;

  @override
  Widget build(BuildContext context) {
    return CoCheckbox(
      state: _state,
      label: 'Disabled',
      enabled: false,
      onChanged: (value) => setState(() => _state = value),
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

  • 여러 옵션 중 하나 이상을 선택할 때 (다중 선택)
  • 약관 동의, 옵션 활성화 등 boolean 값을 입력받을 때
  • "전체 선택" 같은 부분 선택 상태(indeterminate)를 표현할 때

대신 다른 컴포넌트를 사용하세요:

  • Toggle: 즉시 적용되는 on/off 스위치가 필요할 때
  • RadioGroup: 여러 옵션 중 하나만 선택해야 할 때
  • Select: 옵션이 많아 드롭다운으로 보여줘야 할 때

기본 사용법 (Basic Usage)#

// 기본 체크박스
CoCheckbox(
  state: CoreCheckboxState.unchecked,
  onChanged: handleChanged,
  label: '이용약관에 동의합니다',
)

// 체크된 상태
CoCheckbox(
  state: CoreCheckboxState.checked,
  onChanged: handleChanged,
  label: '알림 받기',
)

// 불확정 상태
CoCheckbox(
  state: CoreCheckboxState.indeterminate,
  onChanged: handleChanged,
  tristate: true,
  label: '전체 선택',
)

// 기본 체크박스
CoCheckbox(
  state: CoreCheckboxState.unchecked,
  onChanged: handleChanged,
  label: '이용약관에 동의합니다',
)

// 체크된 상태
CoCheckbox(
  state: CoreCheckboxState.checked,
  onChanged: handleChanged,
  label: '알림 받기',
)

// 불확정 상태
CoCheckbox(
  state: CoreCheckboxState.indeterminate,
  onChanged: handleChanged,
  label: '전체 선택',
)

스타일 시스템 — checkboxStyle (Epic #1302)#

CoCheckbox 의 box chrome / 슬롯 미세 조정은 단일 checkboxStyle (CoreCheckboxStyle) 으로 흐릅니다. 시맨틱 enum (variant, size) 은 위젯 파라미터. 

CoCheckbox(
  variant: CoreCheckboxVariant.defaultVariant,
  size: CoreComponentSize.md,
  state: CoreCheckboxState.checked,
  onChanged: handleChange,
  label: '동의함',
  checkboxStyle: CoreCheckboxStyle(
    boxBorderColor: cs.outline,
    boxActiveColor: cs.primary,
    boxBorderRadius: 4,
    gap: 8,
    checkmarkIconStyle: CoreIconStyle(size: 16, color: cs.onPrimary),
    labelStyle: CoreTextStyle(fontWeight: CoreFontWeight.semiBold),
  ),
)

CoreCheckboxStyle 필드#

필드타입설명
boxBackgroundColor Color? / String? unchecked 배경색
boxActiveColor Color? / String? checked 배경색
boxBorderColorColor? / String?보더 색
boxBorderWidthdouble?보더 두께
boxBorderRadiusdouble?보더 반경
boxSizedouble?box 크기 (width = height)
gapdouble?box ↔ label 간격
checkmarkIconStyle CoreIconStyle? 체크마크 아이콘 (size/color)
labelStyleCoreTextStyle?label 텍스트 스타일

Resolve chain#

design system default for variant
  → CoreCheckboxTheme.style
  → CoreCheckboxTheme.variantStyles[widget.variant]
  → 부모 컴포넌트 슬롯 오버라이드
  → widget.checkboxStyle

Props / Parameters#

속성타입기본값설명
state CoreCheckboxState unchecked 체크 상태 (checked, unchecked, indeterminate)
onChanged ValueChanged<CoreCheckboxState>? null 상태 변경 콜백
labelString?null라벨 텍스트
tristate bool false 3단계 상태 허용 (Flutter)
enabledbool?null활성화 여부
variant CoreCheckboxVariant defaultVariant 시맨틱 변형 (위젯 파라미터)
size CoreComponentSize md 크기 토큰 (위젯 파라미터)
checkboxStyle CoreCheckboxStyle? null box chrome / nested slot 묶음
prefix / suffix Widget? / Component? null 좌/우 슬롯
name / focusNode / statesController / controller platform null form / focus

변형 (Variants)#

상태#

// 체크됨
CoCheckbox(
  state: CoreCheckboxState.checked,
  label: 'Checked',
  onChanged: handleChanged,
)

// 불확정
CoCheckbox(
  state: CoreCheckboxState.indeterminate,
  label: 'Indeterminate',
  onChanged: handleChanged,
)

// 비활성화
CoCheckbox(
  state: CoreCheckboxState.unchecked,
  enabled: false,
  label: 'Disabled',
  onChanged: handleChanged,
)

동작 스펙 (Behavior)#

상태 전환#

  • 2-state (tristate: false): checked ↔ unchecked 토글
  • 3-state (tristate: true): checked → unchecked → indeterminate → checked 순환

사용 가이드라인 (Usage Guidelines)#

✅ Do#

체크박스에 항상 라벨을 제공하세요.

CoCheckbox(
  state: CoreCheckboxState.unchecked,
  onChanged: handleChanged,
  label: '마케팅 이메일 수신에 동의합니다',
)

라벨 영역도 클릭 가능하여 조작이 쉬워집니다.

❌ Don't#

라벨 없이 체크박스만 두지 마세요.

CoCheckbox(
  state: CoreCheckboxState.unchecked,
  onChanged: handleChanged,
)

체크박스의 목적을 알 수 없고, 작은 영역만 클릭 가능합니다.

✅ Do#

긍정형 라벨을 사용하세요.

CoCheckbox(label: '알림 받기', state: CoreCheckboxState.unchecked, onChanged: handleChanged)

체크 = 활성화가 직관적입니다.

❌ Don't#

부정형 라벨을 사용하지 마세요.

CoCheckbox(label: '알림 받지 않기', state: CoreCheckboxState.unchecked, onChanged: handleChanged)

체크하면 "받지 않기"가 되어 이중 부정으로 혼란스럽습니다.

접근성 (Accessibility)#

키보드 인터랙션#

키동작
Space체크박스 토글
Tab다음 체크박스로 포커스 이동
Shift+Tab이전 체크박스로 포커스 이동

관련 컴포넌트 (Related Components)#

  • Toggle: on/off 스위치. 즉시 적용되는 설정에 적합
  • Select: 드롭다운 선택. 옵션이 5개 이상이면 Select가 더 적합
  • Form: 폼 컨테이너. 체크박스를 폼 필드로 등록하여 일괄 검증 가능