Skip to Content

Step

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


개요

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

주요 특징

  • 단계 시각화: 현재/완료/대기 상태를 인디케이터로 표시
  • success / error 상태: 단계별 성공·오류 상태를 별도 토큰으로 시각화
  • 네비게이션: 이전/다음/완료 버튼 제공
  • 필수 입력 검증: canGoNext로 단계 이동 제어
  • 순차 이동 제어: 미래 단계 건너뛰기 방지
  • 완료 콜백: 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 상태

각 단계에 success 또는 error 상태를 지정할 수 있습니다. success는 체크 아이콘, error는 X 아이콘으로 표시되며 각각 별도의 디자인 토큰(--step-head-background-success, --step-head-background-error 등)이 적용됩니다.

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

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


API Reference

Step

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

Events (Step)

EventTypeDescription
onStepChange(step: number) => void단계 변경 시 호출
onComplete() => void최종 완료 시 호출

StepList

PropTypeDefaultDescription
classNamestring-추가 CSS 클래스

StepItem

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

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() => void다음 단계 이동
goToPrev() => void이전 단계 이동
goToStep(step: number) => void특정 단계 이동 (≤ 현재)
canGoNextboolean다음 이동 가능 여부
setCanGoNext(value: boolean) => void다음 이동 가능 여부 설정
stepStatusesRecord<number, "success" | "error">각 단계의 override 상태 맵
setStepStatus(step: number, status: "success" | "error" | null) => void단계 상태 설정 (null이면 초기화)

접근성

권장 사항

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

관련 컴포넌트

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