Stepper#

사용자가 단계를 클릭하여 이동할 수 있는 인터랙티브 프로세스 컴포넌트입니다.

Live Preview#

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

  @override
  State<StepperDefaultExample> createState() => _StepperDefaultExampleState();
}

class _StepperDefaultExampleState extends State<StepperDefaultExample> {
  int _currentStep = 1;

  void handleStepChanged(int index) {
    setState(() {
      _currentStep = index;
    });
  }

  @override
  Component build(BuildContext context) {
    return Stepper(
      currentStep: _currentStep,
      onStepChanged: handleStepChanged,
      steps: const [
        CoreStepItem(label: 'Account', description: 'Create account'),
        CoreStepItem(label: 'Profile', description: 'Set up profile'),
        CoreStepItem(label: 'Complete', description: 'All done'),
      ],
    );
  }
}

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

  @override
  State<StepperDefaultExample> createState() => _StepperDefaultExampleState();
}

class _StepperDefaultExampleState extends State<StepperDefaultExample> {
  int _currentStep = 1;

  void handleStepChanged(int index) {
    setState(() {
      _currentStep = index;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Stepper(
      currentStep: _currentStep,
      onStepChanged: handleStepChanged,
      steps: const [
        CoreStepItem(label: 'Account', description: 'Create account'),
        CoreStepItem(label: 'Profile', description: 'Set up profile'),
        CoreStepItem(label: 'Complete', description: 'All done'),
      ],
    );
  }
}

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

  @override
  State<StepperVerticalExample> createState() => _StepperVerticalExampleState();
}

class _StepperVerticalExampleState extends State<StepperVerticalExample> {
  int _currentStep = 1;

  void handleStepChanged(int index) {
    setState(() {
      _currentStep = index;
    });
  }

  @override
  Component build(BuildContext context) {
    return Stepper(
      currentStep: _currentStep,
      orientation: CoreStepperOrientation.vertical,
      onStepChanged: handleStepChanged,
      steps: const [
        CoreStepItem(label: 'Account', description: 'Create account'),
        CoreStepItem(label: 'Profile', description: 'Set up profile'),
        CoreStepItem(label: 'Complete', description: 'All done'),
      ],
    );
  }
}

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

  @override
  State<StepperVerticalExample> createState() => _StepperVerticalExampleState();
}

class _StepperVerticalExampleState extends State<StepperVerticalExample> {
  int _currentStep = 1;

  void handleStepChanged(int index) {
    setState(() {
      _currentStep = index;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Stepper(
      currentStep: _currentStep,
      orientation: CoreStepperOrientation.vertical,
      onStepChanged: handleStepChanged,
      steps: const [
        CoreStepItem(label: 'Account', description: 'Create account'),
        CoreStepItem(label: 'Profile', description: 'Set up profile'),
        CoreStepItem(label: 'Complete', description: 'All done'),
      ],
    );
  }
}

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

  @override
  State<StepperChainExample> createState() => _StepperChainExampleState();
}

class _StepperChainExampleState extends State<StepperChainExample> {
  int _currentStep = 1;

  void handleStepChanged(int index) {
    setState(() {
      _currentStep = index;
    });
  }

  @override
  Component build(BuildContext context) {
    return Stepper(
      currentStep: _currentStep,
      onStepChanged: handleStepChanged,
      steps: const [
        CoreStepItem(label: 'Account', description: 'Create account'),
        CoreStepItem(label: 'Profile', description: 'Set up profile'),
        CoreStepItem(label: 'Complete', description: 'All done'),
      ],
    ).withStyle(
      const CoreStepperStyle(
        indicatorActiveColor: CoreColor.token(CoreColors.primary),
        indicatorSize: CoreSize.size40,
        connectorThickness: CoreStrokeWidth.stroke6,
        indicatorContentGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

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

  @override
  State<StepperChainExample> createState() => _StepperChainExampleState();
}

class _StepperChainExampleState extends State<StepperChainExample> {
  int _currentStep = 1;

  void handleStepChanged(int index) {
    setState(() {
      _currentStep = index;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Stepper(
      currentStep: _currentStep,
      onStepChanged: handleStepChanged,
      steps: const [
        CoreStepItem(label: 'Account', description: 'Create account'),
        CoreStepItem(label: 'Profile', description: 'Set up profile'),
        CoreStepItem(label: 'Complete', description: 'All done'),
      ],
    ).withStyle(
      const CoreStepperStyle(
        indicatorActiveColor: CoreColor.token(CoreColors.primary),
        indicatorSize: CoreSize.size40,
        connectorThickness: CoreStrokeWidth.stroke6,
        indicatorContentGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

사용 시기 (When to Use)#

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

• 회원가입, 결제, 설정 마법사 등 다단계 폼
• 사용자가 이전 단계로 돌아가거나 특정 단계로 점프할 수 있어야 할 때

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

• Steps: 읽기 전용 진행 상태 표시 (탭 불가)
• Tabs: 독립적인 콘텐츠 간 전환 (순서/진행 개념 없음)

기본 사용법 (Basic Usage)#

Stepper(
  currentStep: 1,
  steps: [
    CoreStepItem(label: 'Account', description: 'Create account'),
    CoreStepItem(label: 'Profile', description: 'Set up profile'),
    CoreStepItem(label: 'Complete', description: 'All done'),
  ],
  onStepChanged: (index) => setState(() => _step = index),
)

Props / Parameters#

스타일 시스템 (Style System)#

Stepper 의 모든 chrome / dimensional / nested-slot 오버라이드는 CoreStepperStyle 단일 슬롯으로 흐릅니다. 시맨틱 enum (orientation) 과 behaviour (steps / currentStep / onStepChanged) 는 위젯/컴포넌트 파라미터로 직접 전달합니다.

시맨틱 vs 스타일#

• 시맨틱 enum / behaviour: 위젯/컴포넌트 파라미터로 직접 (steps, currentStep, orientation, onStepChanged)
• chrome / dimensional / 슬롯 스타일: CoreStepperStyle 한 곳으로 (indicatorActiveColor / indicatorInactiveColor / indicatorBorderColor / indicatorBorderWidth / indicatorSize / connectorActiveColor / connectorInactiveColor / connectorThickness / indicatorContentGapStyle / stepPadding / connectorMargin / horizontalLabelGapStyle / connectorMinExtent / iconSizeRatio / labelStyle / descriptionStyle / indicatorIconStyle)

Resolve chain#

design system default for stepper
  → CoreStepperTheme.style                    // 프로젝트 공통
  → parent component slot override
  → widget.stepperStyle                       // 인스턴스별

각 nested 슬롯 스타일 (labelStyle / descriptionStyle / indicatorIconStyle) 은 자기 컴포넌트의 자체 resolve chain 으로 다시 한 번 머지됩니다.

CoreStepperStyle 필드#

빠른 오버라이드 (Chain)#

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

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

  @override
  State<StepperChainExample> createState() => _StepperChainExampleState();
}

class _StepperChainExampleState extends State<StepperChainExample> {
  int _currentStep = 1;

  void handleStepChanged(int index) {
    setState(() {
      _currentStep = index;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Stepper(
      currentStep: _currentStep,
      onStepChanged: handleStepChanged,
      steps: const [
        CoreStepItem(label: 'Account', description: 'Create account'),
        CoreStepItem(label: 'Profile', description: 'Set up profile'),
        CoreStepItem(label: 'Complete', description: 'All done'),
      ],
    ).withStyle(
      const CoreStepperStyle(
        indicatorActiveColor: CoreColor.token(CoreColors.primary),
        indicatorSize: CoreSize.size40,
        connectorThickness: CoreStrokeWidth.stroke6,
        indicatorContentGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

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

  @override
  State<StepperChainExample> createState() => _StepperChainExampleState();
}

class _StepperChainExampleState extends State<StepperChainExample> {
  int _currentStep = 1;

  void handleStepChanged(int index) {
    setState(() {
      _currentStep = index;
    });
  }

  @override
  Component build(BuildContext context) {
    return Stepper(
      currentStep: _currentStep,
      onStepChanged: handleStepChanged,
      steps: const [
        CoreStepItem(label: 'Account', description: 'Create account'),
        CoreStepItem(label: 'Profile', description: 'Set up profile'),
        CoreStepItem(label: 'Complete', description: 'All done'),
      ],
    ).withStyle(
      const CoreStepperStyle(
        indicatorActiveColor: CoreColor.token(CoreColors.primary),
        indicatorSize: CoreSize.size40,
        connectorThickness: CoreStrokeWidth.stroke6,
        indicatorContentGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

변형 (Variants)#

가로 배치#

Stepper(
  currentStep: 1,
  orientation: CoreStepperOrientation.horizontal,
  steps: [
    CoreStepItem(label: '기본 정보'),
    CoreStepItem(label: '주소 입력'),
    CoreStepItem(label: '결제 수단'),
    CoreStepItem(label: '확인'),
  ],
  onStepChanged: (i) => setState(() => _step = i),
)

세로 배치#

Stepper(
  currentStep: 1,
  orientation: CoreStepperOrientation.vertical,
  steps: [
    CoreStepItem(label: '기본 정보', description: '이름과 이메일'),
    CoreStepItem(label: '주소 입력', description: '배송지 설정'),
    CoreStepItem(label: '결제 수단', description: '카드 등록'),
  ],
  onStepChanged: (i) => setState(() => _step = i),
)

동작 스펙 (Behavior)#

상태 표시#

• currentStep 미만: 완료 (primary 원 + 체크 아이콘)
• currentStep 인덱스: 현재 (primary 원 + 번호, 볼드 라벨)
• currentStep 초과: 대기 (surfaceContainer 원 + 번호)

인터랙션#

• 각 단계 인디케이터 클릭 → onStepChanged(index) 호출
• 키보드 네비게이션은 표준 Tab 순서 따름

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

✅ Do#

Stepper(
  currentStep: step,
  steps: steps,
  onStepChanged: (index) {
    if (index <= step) setState(() => step = index); // 완료된 단계로만 되돌아가기 허용
  },
)

❌ Don't#

// ❌ 읽기 전용 진행 표시가 목적인데 onStepChanged를 채워둠
Stepper(
  currentStep: step,
  steps: steps,
  onStepChanged: (_) {},
)

접근성 (Accessibility)#

키보드#

스크린 리더#

• 각 단계는 순서 + 라벨 + 설명 읽음
• 완료/현재/대기 상태 시각 표시 기반

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

관련 컴포넌트 (Related Components)#

• Steps: 읽기 전용 진행 상태 표시
• Tabs: 독립적인 콘텐츠 전환
• Progress: 단일 진행률 표시