Steps | CoUI
LogoCoUI

Steps

진행 단계를 시각적으로 표시하는 스텝 인디케이터

원문 .md 보기 Open in Claude

Steps#

다단계 진행 상황을 시각적으로 표시하는 읽기 전용 컴포넌트입니다.

Live Preview#

default
Web
Create Account
Sign up with your email
Verify Email
Check your inbox
3
Setup Profile
Add your information
4
Complete
Ready to go
Flutter
Loading Flutter... 
class StepsDefaultExample extends StatelessComponent {
  const StepsDefaultExample({super.key});

  @override
  Component build(BuildContext context) {
    return const Steps(
      currentStep: 2,
      items: [
        CoreStepData(
          title: 'Create Account',
          description: 'Sign up with your email',
        ),
        CoreStepData(
          title: 'Verify Email',
          description: 'Check your inbox',
        ),
        CoreStepData(
          title: 'Setup Profile',
          description: 'Add your information',
        ),
        CoreStepData(
          title: 'Complete',
          description: 'Ready to go',
        ),
      ],
    );
  }
}
class StepsDefaultExample extends StatelessWidget {
  const StepsDefaultExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const Steps(
      currentStep: 2,
      items: [
        CoreStepData(
          title: 'Create Account',
          description: 'Sign up with your email',
        ),
        CoreStepData(
          title: 'Verify Email',
          description: 'Check your inbox',
        ),
        CoreStepData(
          title: 'Setup Profile',
          description: 'Add your information',
        ),
        CoreStepData(
          title: 'Complete',
          description: 'Ready to go',
        ),
      ],
    );
  }
}
horizontal
Web
Cart
2
Shipping
3
Payment
4
Review
Flutter
Loading Flutter... 
class StepsHorizontalExample extends StatelessComponent {
  const StepsHorizontalExample({super.key});

  @override
  Component build(BuildContext context) {
    return const Steps(
      currentStep: 1,
      vertical: false,
      items: [
        CoreStepData(title: 'Cart'),
        CoreStepData(title: 'Shipping'),
        CoreStepData(title: 'Payment'),
        CoreStepData(title: 'Review'),
      ],
    );
  }
}
class StepsHorizontalExample extends StatelessWidget {
  const StepsHorizontalExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const Steps(
      currentStep: 1,
      vertical: false,
      items: [
        CoreStepData(title: 'Cart'),
        CoreStepData(title: 'Shipping'),
        CoreStepData(title: 'Payment'),
        CoreStepData(title: 'Review'),
      ],
    );
  }
}
chain
Web
Create Account
Sign up with your email
Verify Email
Check your inbox
3
Setup Profile
Add your information
4
Complete
Ready to go
Flutter
Loading Flutter... 
class StepsChainExample extends StatelessComponent {
  const StepsChainExample({super.key});

  @override
  Component build(BuildContext context) {
    return const Steps(
      currentStep: 2,
      items: [
        CoreStepData(
          title: 'Create Account',
          description: 'Sign up with your email',
        ),
        CoreStepData(
          title: 'Verify Email',
          description: 'Check your inbox',
        ),
        CoreStepData(
          title: 'Setup Profile',
          description: 'Add your information',
        ),
        CoreStepData(
          title: 'Complete',
          description: 'Ready to go',
        ),
      ],
    ).withStyle(
      const CoreStepsStyle(
        indicatorSize: CoreSize.size40,
        activeIndicatorColor: CoreColor.token(CoreColors.primary),
        connectorThickness: CoreStrokeWidth.stroke4,
        indicatorContentGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}
class StepsChainExample extends StatelessWidget {
  const StepsChainExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const Steps(
      currentStep: 2,
      items: [
        CoreStepData(
          title: 'Create Account',
          description: 'Sign up with your email',
        ),
        CoreStepData(
          title: 'Verify Email',
          description: 'Check your inbox',
        ),
        CoreStepData(
          title: 'Setup Profile',
          description: 'Add your information',
        ),
        CoreStepData(
          title: 'Complete',
          description: 'Ready to go',
        ),
      ],
    ).withStyle(
      const CoreStepsStyle(
        indicatorSize: CoreSize.size40,
        activeIndicatorColor: CoreColor.token(CoreColors.primary),
        connectorThickness: CoreStrokeWidth.stroke4,
        indicatorContentGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

사용 시기 (When to Use)#

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

  • 주문 진행, 배송 추적, 절차 안내 등 진행 단계를 보여줄 때
  • 각 단계의 완료/진행/대기 상태를 시각적으로 구분해야 할 때

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

  • Stepper: 사용자가 단계를 클릭하여 이동할 수 있는 인터랙티브 프로세스
  • Progress: 단일 진행률을 바 형태로 표시

기본 사용법 (Basic Usage)#

Steps(
  currentStep: 2,
  items: [
    CoreStepData(
      title: 'Create Account',
      description: 'Sign up with your email',
    ),
    CoreStepData(
      title: 'Verify Email',
      description: 'Check your inbox',
    ),
    CoreStepData(
      title: 'Setup Profile',
      description: 'Add your information',
    ),
    CoreStepData(
      title: 'Complete',
      description: 'Ready to go',
    ),
  ],
)

빠른 오버라이드 (Chain)#

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

class StepsChainExample extends StatelessWidget {
  const StepsChainExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const Steps(
      currentStep: 2,
      items: [
        CoreStepData(
          title: 'Create Account',
          description: 'Sign up with your email',
        ),
        CoreStepData(
          title: 'Verify Email',
          description: 'Check your inbox',
        ),
        CoreStepData(
          title: 'Setup Profile',
          description: 'Add your information',
        ),
        CoreStepData(
          title: 'Complete',
          description: 'Ready to go',
        ),
      ],
    ).withStyle(
      const CoreStepsStyle(
        indicatorSize: CoreSize.size40,
        activeIndicatorColor: CoreColor.token(CoreColors.primary),
        connectorThickness: CoreStrokeWidth.stroke4,
        indicatorContentGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

class StepsChainExample extends StatelessComponent {
  const StepsChainExample({super.key});

  @override
  Component build(BuildContext context) {
    return const Steps(
      currentStep: 2,
      items: [
        CoreStepData(
          title: 'Create Account',
          description: 'Sign up with your email',
        ),
        CoreStepData(
          title: 'Verify Email',
          description: 'Check your inbox',
        ),
        CoreStepData(
          title: 'Setup Profile',
          description: 'Add your information',
        ),
        CoreStepData(
          title: 'Complete',
          description: 'Ready to go',
        ),
      ],
    ).withStyle(
      const CoreStepsStyle(
        indicatorSize: CoreSize.size40,
        activeIndicatorColor: CoreColor.token(CoreColors.primary),
        connectorThickness: CoreStrokeWidth.stroke4,
        indicatorContentGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

Props / Parameters#

속성타입기본값설명
items List<CoreStepData> 필수 단계 데이터 목록
currentStep int 0 현재 활성 단계 인덱스 (0-based)
verticalbooltrue세로 배치 여부
stepsStyle CoreStepsStyle? null 인스턴스별 chrome 단일 진입점

CoreStepData#

속성타입기본값설명
titleString필수단계 제목
description String? null 선택적 부가 설명

CoreStepsStyle 필드#

필드타입설명
indicatorSize double? Indicator circle diameter (logical px).
indicatorBorderRadius CoreBorderRadius? Indicator (circle) corner radius override. Falls back to [defaultIndicatorBorderRadius] (a full circle) when null.
stepPadding CoreEdgeInsets? Padding below each step content in the vertical layout. Falls back to [defaultStepPadding] when null.
stepPaddingHorizontal CoreEdgeInsets? Outer padding around each step content in the horizontal layout — carries the top + right insets (the widget zeroes the right inset on the last item so the connector still ends cleanly).
connectorThickness double? Connector line stroke thickness (logical px).
iconSizeRatio double? Check icon size ratio relative to the indicator diameter.
indicatorColor CoreColor? Inactive indicator and connector fill colour. Falls back to [defaultIndicatorColor].
activeIndicatorColor CoreColor? Active indicator / completed-connector fill colour. Falls back to [defaultActiveIndicatorColor].
activeLabelColor CoreColor? Label colour inside completed / current step indicators (on the active fill). Falls back to [defaultActiveLabelColor].
inactiveLabelColor CoreColor? Label colour inside upcoming step indicators (on the inactive fill). Falls back to [defaultInactiveLabelColor].
titleColor CoreColor? Content title colour. Falls back to [defaultTitleColor].
descriptionColor CoreColor? Content description colour. Falls back to [defaultDescriptionColor].
labelStyle CoreTextStyle? Indicator label typography. Merged on top of [defaultLabelStyle].
titleStyle CoreTextStyle? Content title typography. Merged on top of [defaultTitleStyle].
descriptionStyle CoreTextStyle? Content description typography. Merged on top of [defaultDescriptionStyle].
indicatorContentGapStyle CoreGapStyle? Nested [CoreGapStyle] slot for the gap between the indicator column and the step content. Merged on top of [defaultIndicatorContentGapStyle].
indicatorConnectorGapStyle CoreGapStyle? Nested [CoreGapStyle] slot for the gap above and below the connector line inside the indicator column. Merged on top of [defaultIndicatorConnectorGapStyle].

변형 (Variants)#

세로 (기본)#

Steps(
  currentStep: 2,
  items: [
    CoreStepData(title: 'Create Account', description: 'Sign up with your email'),
    CoreStepData(title: 'Verify Email', description: 'Check your inbox'),
    CoreStepData(title: 'Setup Profile', description: 'Add your information'),
    CoreStepData(title: 'Complete', description: 'Ready to go'),
  ],
)

가로 (vertical: false)#

Steps(
  currentStep: 1,
  vertical: false,
  items: [
    CoreStepData(title: 'Cart'),
    CoreStepData(title: 'Shipping'),
    CoreStepData(title: 'Payment'),
    CoreStepData(title: 'Review'),
  ],
)

가로 레이아웃은 인디케이터가 동일한 행에 배치되고, 인디케이터 사이에 가로 커넥터 라인이 그려집니다. 각 단계의 콘텐츠는 인디케이터 아래에 배치됩니다.

동작 스펙 (Behavior)#

상태 표시#

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

커넥터#

  • 단계 간 선으로 연결 (세로 레이아웃: 세로선, 가로 레이아웃: 가로선)
  • 이전 단계가 완료된 경우 primary 색상
  • 이후 단계는 surfaceContainer 색상

인터랙션#

  • 읽기 전용 — 탭/클릭 동작 없음
  • 인터랙티브한 단계 네비게이션은 Stepper 사용

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

✅ Do#

진행 상태만 필요하면 Steps, 클릭 이동이 필요하면 Stepper

Steps(
  currentStep: 2,
  items: [
    CoreStepData(title: 'Create Account', description: 'Sign up with your email'),
    CoreStepData(title: 'Verify Email'),
    CoreStepData(title: 'Setup Profile'),
  ],
)

Steps는 currentStep 값 하나로 완료/현재/대기 상태를 색상과 아이콘으로 자동 표시합니다 — 각 단계의 색을 직접 계산할 필요가 없습니다.

❌ Don't#

클릭 가능한 것처럼 감싸서 인터랙션을 흉내내지 않기

// ❌ Steps는 콜백이 없어 탭해도 아무 일도 일어나지 않음
GestureDetector(
  onTap: () => setState(() => step++),
  child: Steps(currentStep: step, items: items),
)

Steps는 읽기 전용 컴포넌트입니다 — items(CoreStepData)는 title/description만 받고 클릭 콜백 자체가 없습니다. 단계를 클릭해 이동해야 한다면 Stepper를 사용하세요.

접근성 (Accessibility)#

스크린 리더#

  • 각 단계는 순서대로 읽힘 (title + description)
  • 완료 상태의 체크 아이콘은 시각적 표시용

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

항목FlutterWeb
클래스명StepsSteps
렌더링 Column + Row + Container <div> + 인라인 스타일
아이콘 Icon(LucideIcons.check) Icon(LucideIcons.check)
테마CoreStepsThemeCoreStepsTheme
  • Stepper: 사용자가 클릭으로 이동 가능한 인터랙티브 버전
  • Progress: 단일 진행률 표시