Toggle#

켜기/끄기 상태를 전환하는 토글 스위치 컴포넌트입니다.

Live Preview#

class ToggleDefaultExample extends StatefulComponent {
  const ToggleDefaultExample({super.key});

  @override
  State<ToggleDefaultExample> createState() => _ToggleDefaultExampleState();
}

class _ToggleDefaultExampleState extends State<ToggleDefaultExample> {
  bool _value = false;

  @override
  Component build(BuildContext context) {
    return Toggle(
      value: _value,
      label: 'Toggle',
      onChanged: (v) => setState(() => _value = v),
    );
  }
}

class ToggleDefaultExample extends StatefulWidget {
  const ToggleDefaultExample({super.key});

  @override
  State<ToggleDefaultExample> createState() => _ToggleDefaultExampleState();
}

class _ToggleDefaultExampleState extends State<ToggleDefaultExample> {
  bool _value = false;

  @override
  Widget build(BuildContext context) {
    return Toggle(
      value: _value,
      onChanged: (v) => setState(() => _value = v),
      label: 'Toggle',
    );
  }
}

class ToggleOnExample extends StatefulComponent {
  const ToggleOnExample({super.key});

  @override
  State<ToggleOnExample> createState() => _ToggleOnExampleState();
}

class _ToggleOnExampleState extends State<ToggleOnExample> {
  bool _value = true;

  @override
  Component build(BuildContext context) {
    return Toggle(
      value: _value,
      label: 'Toggle',
      onChanged: (v) => setState(() => _value = v),
    );
  }
}

class ToggleOnExample extends StatefulWidget {
  const ToggleOnExample({super.key});

  @override
  State<ToggleOnExample> createState() => _ToggleOnExampleState();
}

class _ToggleOnExampleState extends State<ToggleOnExample> {
  bool _value = true;

  @override
  Widget build(BuildContext context) {
    return Toggle(
      value: _value,
      onChanged: (v) => setState(() => _value = v),
      label: 'Toggle',
    );
  }
}

class ToggleDisabledExample extends StatefulComponent {
  const ToggleDisabledExample({super.key});

  @override
  State<ToggleDisabledExample> createState() => _ToggleDisabledExampleState();
}

class _ToggleDisabledExampleState extends State<ToggleDisabledExample> {
  bool _value = false;

  @override
  Component build(BuildContext context) {
    return Toggle(
      value: _value,
      label: 'Toggle',
      enabled: false,
      onChanged: (value) {
        setState(() {
          _value = value;
        });
      },
    );
  }
}

class ToggleDisabledExample extends StatefulWidget {
  const ToggleDisabledExample({super.key});

  @override
  State<ToggleDisabledExample> createState() => _ToggleDisabledExampleState();
}

class _ToggleDisabledExampleState extends State<ToggleDisabledExample> {
  bool _value = false;

  @override
  Widget build(BuildContext context) {
    return Toggle(
      value: _value,
      enabled: false,
      label: 'Toggle',
      onChanged: (value) {
        setState(() {
          _value = value;
        });
      },
    );
  }
}

class ToggleChainExample extends StatefulComponent {
  const ToggleChainExample({super.key});

  @override
  State<ToggleChainExample> createState() => _ToggleChainExampleState();
}

class _ToggleChainExampleState extends State<ToggleChainExample> {
  bool _value = false;

  @override
  Component build(BuildContext context) {
    return Toggle(
      value: _value,
      onChanged: (v) => setState(() => _value = v),
      label: 'Toggle',
    ).withStyle(
      const CoreToggleStyle(
        trackActiveColor: CoreColor.token(CoreColors.success),
        trackInactiveColor: CoreColor.token(CoreColors.outlineVariant),
        trackBorderRadius: CoreBorderRadius.all(CoreRadius.radius4),
        thumbBorderRadius: CoreBorderRadius.all(CoreRadius.radius2),
        iconLabelGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

class ToggleChainExample extends StatefulWidget {
  const ToggleChainExample({super.key});

  @override
  State<ToggleChainExample> createState() => _ToggleChainExampleState();
}

class _ToggleChainExampleState extends State<ToggleChainExample> {
  bool _value = false;

  @override
  Widget build(BuildContext context) {
    return Toggle(
      value: _value,
      onChanged: (v) => setState(() => _value = v),
      label: 'Toggle',
    ).withStyle(
      const CoreToggleStyle(
        trackActiveColor: CoreColor.token(CoreColors.success),
        trackInactiveColor: CoreColor.token(CoreColors.outlineVariant),
        trackBorderRadius: CoreBorderRadius.all(CoreRadius.radius4),
        thumbBorderRadius: CoreBorderRadius.all(CoreRadius.radius2),
        iconLabelGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

사용 시기 (When to Use)#

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

• 즉시 적용되는 on/off 설정을 전환할 때 (다크 모드, 알림 등)
• 두 가지 상태만 있고 변경이 바로 반영될 때
• 설정 목록에서 각 옵션을 개별적으로 토글할 때

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

• Checkbox: 폼 제출 후에 반영되는 선택일 때
• Select: 두 가지 이상의 옵션 중 선택할 때
• Button: 단순 액션 트리거일 때 (상태 보존 불필요)

기본 사용법 (Basic Usage)#

// 기본 토글
Toggle(
  value: isDarkMode,
  onChanged: handleDarkModeToggle,
)

// 라벨 텍스트
Toggle(
  value: isNotificationEnabled,
  onChanged: handleNotificationToggle,
  label: '알림 수신',
)

// 앞에 라벨 Widget 배치
Toggle(
  value: isActive,
  onChanged: handleToggle,
  prefix: Text('자동 저장'),
)

// 뒤에 라벨 Widget 배치
Toggle(
  value: isActive,
  onChanged: handleToggle,
  suffix: Text('자동 저장'),
)

// 비활성화
Toggle(
  value: false,
  onChanged: null,
  enabled: false,
  label: '비활성 옵션',
)

// 기본 토글
Toggle(
  value: isDarkMode,
  onChanged: handleDarkModeToggle,
)

// 라벨 텍스트
Toggle(
  value: isNotificationEnabled,
  onChanged: handleNotificationToggle,
  label: '알림 수신',
)

// 비활성화
Toggle(
  value: false,
  enabled: false,
)

// 초기 상태 on
Toggle(
  value: true,
  onChanged: handleToggle,
)

Props / Parameters#

Flutter 전용 런타임 인프라 (Web 은 브라우저 native focus / DOM 이 같은 capability 를 제공):

빠른 오버라이드 (Chain)#

이미 만든 Toggle 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다.

class ToggleChainExample extends StatefulWidget {
  const ToggleChainExample({super.key});

  @override
  State<ToggleChainExample> createState() => _ToggleChainExampleState();
}

class _ToggleChainExampleState extends State<ToggleChainExample> {
  bool _value = false;

  @override
  Widget build(BuildContext context) {
    return Toggle(
      value: _value,
      onChanged: (v) => setState(() => _value = v),
      label: 'Toggle',
    ).withStyle(
      const CoreToggleStyle(
        trackActiveColor: CoreColor.token(CoreColors.success),
        trackInactiveColor: CoreColor.token(CoreColors.outlineVariant),
        trackBorderRadius: CoreBorderRadius.all(CoreRadius.radius4),
        thumbBorderRadius: CoreBorderRadius.all(CoreRadius.radius2),
        iconLabelGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

class ToggleChainExample extends StatefulComponent {
  const ToggleChainExample({super.key});

  @override
  State<ToggleChainExample> createState() => _ToggleChainExampleState();
}

class _ToggleChainExampleState extends State<ToggleChainExample> {
  bool _value = false;

  @override
  Component build(BuildContext context) {
    return Toggle(
      value: _value,
      onChanged: (v) => setState(() => _value = v),
      label: 'Toggle',
    ).withStyle(
      const CoreToggleStyle(
        trackActiveColor: CoreColor.token(CoreColors.success),
        trackInactiveColor: CoreColor.token(CoreColors.outlineVariant),
        trackBorderRadius: CoreBorderRadius.all(CoreRadius.radius4),
        thumbBorderRadius: CoreBorderRadius.all(CoreRadius.radius2),
        iconLabelGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

스타일 시스템 — toggleStyle#

Toggle 의 track + thumb chrome / 슬롯 미세 조정은 단일 toggleStyle (CoreToggleStyle) 으로 흐릅니다. 시맨틱 enum (variant, size) 은 위젯 파라미터.

Toggle(
  variant: CoreToggleVariant.defaultVariant,
  size: CoreComponentSize.md,
  value: enabled,
  onChanged: handleChange,
  label: '알림 받기',
  toggleStyle: CoreToggleStyle(
    trackActiveColor: CoreColor.token(CoreColors.primary),
    trackInactiveColor: CoreColor.token(CoreColors.outline),
    thumbActiveColor: CoreColor.token(CoreColors.onPrimary),
    thumbInactiveColor: CoreColor.token(CoreColors.onSurface),
    trackBorderRadius: CoreBorderRadius.all(CoreRadius.radius12),
    iconLabelGapStyle: CoreGapStyle(size: CoreSpace.space8),
    labelStyle: CoreTextStyle(fontWeight: CoreFontWeight.semiBold),
  ),
)

CoreToggleStyle 필드#

CoreToggleStyle 변형별 기본값 (CoreToggleVariantStyle)#

variant 별 색은 CoreToggleVariantStyle (activeTrack / inactiveTrack / activeThumb / inactiveThumb / disabledTrack / disabledThumb / disabledForeground) 로 CoreToggleStyle.defaultsByVariant 에서, 크기는 CoreToggleStyle.defaultsBySize 에서 결정됩니다.

Resolve chain#

design system default
  → CoreToggleTheme.style                      // 프로젝트 공통
  → parent component slot override
  → widget.toggleStyle                         // 인스턴스별

nested labelStyle 은 자기 컴포넌트의 resolve chain 으로 다시 한 번 머지됩니다.

변형 (Variants)#

크기#

Toggle(value: v1, onChanged: handle, size: CoreComponentSize.sm)
Toggle(value: v2, onChanged: handle, size: CoreComponentSize.md)
Toggle(value: v3, onChanged: handle, size: CoreComponentSize.lg)

설정 목록에서 사용#

Column(
  children: [
    Toggle(
      value: settings.darkMode,
      onChanged: handleDarkMode,
      label: '다크 모드',
    ),
    Toggle(
      value: settings.notifications,
      onChanged: handleNotifications,
      label: '푸시 알림',
    ),
    Toggle(
      value: settings.autoSave,
      onChanged: handleAutoSave,
      label: '자동 저장',
    ),
  ],
)

동작 스펙 (Behavior)#

상태 전환#

• 클릭/탭 시 value가 true ↔ false 토글
• enabled: false(또는 onChanged: null)면 인터랙션 비활성 + disabled 색 토큰 적용

상태 관리#

// 직접 콜백 방식
Toggle(
  value: isDarkMode,
  onChanged: (value) => setState(() => isDarkMode = value),
)

애니메이션#

• Flutter: 100ms, Curves.easeInOut
  • 트랙 색상: AnimatedContainer로 활성/비활성 색상 전환
  • 썸네일 이동: AnimatedPositioned로 좌우 슬라이딩
• Web: CSS transition-transform으로 썸네일 위치 전환

크기 토큰#

트랙 높이는 6단계 사다리(12/16/20/24/28/32 — Switch/Checkbox/Radio 세 컨트롤이 공유하는 값, epic-k-dimension-table.md §축4)를 따른다. Track 너비와 Thumb 크기는 트랙 높이의 파생값이다: 너비 = 높이 × 1.625, Thumb = 높이 − 2.

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

✅ Do#

Toggle(
  value: isDarkMode,
  onChanged: handleDarkMode,
  label: '다크 모드',
)

❌ Don't#

Toggle(
  value: isDarkMode,
  onChanged: handleDarkMode,
)

✅ Do#

Toggle(
  value: notifications,
  onChanged: (value) {
    updateNotificationSetting(value); // 즉시 서버 반영
  },
  label: '푸시 알림',
)

❌ Don't#

✅ Do#

Toggle(label: '알림 받기', ...)
Toggle(label: '자동 저장', ...)

❌ Don't#

Toggle(label: '알림 끄기', ...)

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

• Flutter: Clickable 위젯으로 플랫폼 시맨틱 전달. 포커스 시 라벨과 상태(켜짐/꺼짐) 읽힘
• Web: role="switch" + aria-checked="true|false"로 스위치 역할 명시. 스크린 리더가 "스위치, 켜짐" 형태로 읽음

포커스 표시#

• Flutter: Clickable 위젯의 포커스 링
• Web: focus-visible:ring-2 focus-visible:ring-ring CSS 포커스 링

비활성 상태#

양 플랫폼 모두 불투명도가 아니라 전용 disabled 색 토큰(CoreToggleVariantStyle 의 disabledTrack / disabledThumb / disabledForeground)으로 표현합니다 — 색 강제 모드에서도 비활성이 활성처럼 읽히지 않습니다.

• Flutter: 트랙 / thumb / 라벨 색을 disabled 토큰으로 교체 + 인터랙션 차단
• Web: 같은 disabled 토큰 class + hidden <input> 의 disabled 속성

크로스 플랫폼 차이점 (Platform Differences)#

Toggle은 coui_core의 CoreToggleVariantStyle과 CoreToggleStyle.defaultsBySize를 사용하여 Flutter/Web 동일한 디자인 토큰 기반으로 렌더링됩니다.

관련 컴포넌트 (Related Components)#

• Checkbox: 체크박스. "제출 후 적용"되는 선택에 적합 (Toggle은 즉시 적용)
• Slider: 범위 값 조절. boolean이 아닌 연속 값일 때
• Form: 폼 컨테이너. Toggle을 폼 필드로 등록 가능

조합 예제#

// 설정 페이지 패턴
Drawer(
  title: '설정',
  content: Column(children: [
    Toggle(
      value: settings.darkMode,
      onChanged: handleDarkMode,
      label: '다크 모드',
    ),
    Toggle(
      value: settings.notifications,
      onChanged: handleNotifications,
      label: '푸시 알림',
    ),
    Toggle(
      value: settings.autoSave,
      onChanged: handleAutoSave,
      label: '자동 저장',
    ),
    Toggle(
      value: settings.analytics,
      onChanged: handleAnalytics,
      label: '사용 통계 수집',
      enabled: !settings.isGuest,
    ),
  ]),
)