Skip to Content

Step

업무 진행 단계를 시각적으로 표시하는 스텝 컴포넌트


개요

Step 컴포넌트는 멀티 스텝 업무 흐름을 시각적으로 안내합니다. 단계 표시, 이전/다음 네비게이션, 필수 입력 검증, 완료 처리 등을 지원합니다.

주요 특징

  • 단계 시각화: 현재/완료/대기 상태를 인디케이터로 표시
  • success / error / current 상태: 단계별 성공·오류·작성중 상태를 별도 토큰으로 시각화
  • 단계 비활성화: StepItem의 disabled로 특정 단계 클릭 차단
  • 인디케이터 이동 정책: 방문한 단계만 인디케이터 클릭으로 이동 가능 (검증 없이 즉시 이동). 미방문 단계는 다음 버튼으로만 진입
  • 네비게이션: 이전/다음/완료 버튼 제공
  • 필수 입력 검증: canGoNext로 다음 단계 이동 제어
  • 비동기 검증: onBeforeStepChange로 서버 요청 등 비동기 검증 후 이동 제어
  • 완료 콜백: onComplete로 최종 처리
  • 라벨/설명: StepTitle, StepDescription 지원

사용 예시

기본 사용

1
Step 1
2
Step 2
3
Step 3
Step 1 콘텐츠

설명 포함

1
기본 정보
이름, 이메일 입력
2
상세 정보
주소, 연락처 입력
3
확인
입력 정보 확인 및 제출
기본 정보 입력

필수 입력 검증

1
이름 입력
2
상세 정보
3
완료

필수 입력 항목입니다.

완료 확인 처리

1
입력
2
확인
입력 단계입니다.

네비게이션 커스텀

1
Step 1
2
Step 2
3
Step 3
Step 1 콘텐츠

success / error / current 상태

각 단계에 success, error, current 상태를 지정할 수 있습니다. success는 체크 아이콘, error는 X 아이콘, current는 숫자(작성중)로 표시되며 각각 별도의 디자인 토큰이 적용됩니다.

성공 단계
오류 단계
3
현재 단계

버튼을 눌러 각 단계의 상태를 변경해보세요.


API Reference

Step

PropTypeDefaultDescription
totalStepsnumber-전체 단계 수 (필수)
defaultStepnumber0초기 단계
initialStepStatusesRecord<number, "success" | "error" | "current">{}각 단계의 초기 상태 (success/error/current)
classNamestring-추가 CSS 클래스

Events (Step)

EventTypeDescription
onBeforeStepChange(from: number, to: number) => boolean | Promise<boolean>단계 이동 직전 호출. false 반환 시 이동 차단 (비동기 지원)
onStepChange(step: number) => void단계 변경 시 호출
onComplete() => void최종 완료 시 호출

StepList

PropTypeDefaultDescription
classNamestring-추가 CSS 클래스

StepItem

PropTypeDefaultDescription
stepnumber-단계 인덱스 (0-based)
disabledboolean-클릭 비활성화 (opacity-50, 클릭 이벤트 차단)

StepIndicator

PropTypeDefaultDescription
stepnumber-단계 인덱스 (0-based)

StepTitle

PropTypeDefaultDescription
stepnumber-단계 인덱스 (0-based)

StepDescription

PropTypeDefaultDescription
stepnumber-단계 인덱스 (0-based)

StepContent

PropTypeDefaultDescription
stepnumber-단계 인덱스 (0-based)

StepNavigation

PropTypeDefaultDescription
prevLabelReact.ReactNode"이전"이전 버튼 텍스트
nextLabelReact.ReactNode"다음"다음 버튼 텍스트
completeLabelReact.ReactNode"완료"완료 버튼 텍스트
showPrevbooleantrue이전 버튼 표시

StepStatus 타입

type StepStatus = "pending" | "current" | "completed" | "success" | "error"
설명아이콘
pending아직 진행되지 않은 단계숫자
current현재 진행 중인 단계숫자
completed정상 완료된 단계 (다음 단계 진입 시)체크 아이콘
success명시적 성공 처리된 단계체크 아이콘
error오류 상태로 표시된 단계X 아이콘

useStep Hook

반환값TypeDescription
currentStepnumber현재 단계
totalStepsnumber전체 단계 수
goToNext() => Promise<void>다음 단계 이동
goToPrev() => Promise<void>이전 단계 이동
goToStep(step: number) => Promise<void>특정 단계로 이동 (검증 없이 즉시 이동, visited 처리 자동)
canGoNextboolean다음 이동 가능 여부
setCanGoNext(value: boolean) => void다음 이동 가능 여부 설정
stepStatusesRecord<number, "success" | "error" | "current">각 단계의 override 상태 맵
setStepStatus(step: number, status: "success" | "error" | "current" | null) => void단계 상태 설정 (null이면 초기화)
visitedStepsReadonlySet<number>방문한 단계 인덱스 집합

접근성

권장 사항

  • ✅ 각 단계에 명확한 라벨(StepTitle) 제공
  • ✅ 현재 단계와 완료 단계를 시각적으로 구분
  • ✅ 비활성 다음 버튼으로 입력 필요성 안내

관련 컴포넌트

  • Tabs: 탭 기반 콘텐츠 전환
  • Dialog: 모달 대화상자
Last updated on