Timeline

순서가 있는 단계들을 시간 흐름대로 나열합니다. 주문 처리 상태나 배포 이력처럼 순서 자체가 정보인 목록에 씁니다.

import { Timeline, TimelineItem } from 'neba';

<Timeline active={2}>
  <TimelineItem title="주문" meta="7월 12일">
    결제가 완료되었습니다.
  </TimelineItem>
  <TimelineItem title="배송 중" meta="7월 14일" />
  <TimelineItem title="배송 완료" />
</Timeline>;

TimelineChart와 다른 컴포넌트입니다. 그쪽은 달력 위에 기간을 그리는 Gantt 차트로 각 작업이 얼마나 걸렸는지를 보여 주고, 이쪽은 단계의 목록이라 단계 사이의 간격은 실제 시간에 비례하지 않습니다.

Props

Timeline

Prop	타입	기본값	설명
active	number	—	지금 진행 중인 항목의 인덱스. 그 앞은 전부 complete, 뒤는 전부 upcoming이 됩니다. 생략하면 전부 upcoming이고, 항목 수를 넘기면 전부 complete입니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	높이와 타입 스케일
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할. 임의 색상값은 받지 않습니다
density공통	'default' | 'compact'	'default'	항목 사이의 간격만 바꿉니다. 타입 스케일도 불릿도 그대로입니다
orientation공통	'horizontal' | 'vertical'	'vertical'	진행 방향. vertical이 기본이며 단계 수와 설명 길이에 제한이 없습니다. horizontal은 결제 화면 위쪽의 스테퍼로, 라벨이 짧을 때만 정직합니다
render	useRender.RenderProp	—	div 대신 다른 요소로 렌더링합니다 (render={<ul />}). Base UI의 render prop 그대로
children	ReactNode	—	TimelineItem들. 인덱스는 여기서 매겨지므로 중간에 하나를 끼워 넣어도 뒤의 것을 다시 번호 매길 필요가 없습니다

active는 값이 아니라 인덱스입니다. 이 인덱스보다 앞선 항목은 complete, 해당 항목은 current, 뒤는 upcoming이 됩니다. 생략하면 전부 upcoming, 항목 수보다 큰 값을 주면 전부 complete입니다.

TimelineItem

Prop	타입	기본값	설명
title	ReactNode	—	이 단계의 제목
meta	ReactNode	—	언제 일어났는지, 날짜, 소요 시간, 이름
bullet	ReactNode	—	불릿 안에 들어가는 것, 번호, 아이콘, 아바타. 생략하면 그냥 원입니다
status	'complete' | 'current' | 'upcoming'	—	타임라인의 active가 계산한 값을 이 항목에 한해 덮어씁니다. 실패해서 멈춘 단계, 건너뛴 단계
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	—	이 항목에 한해 색 계열을 덮어씁니다
connector	'solid' | 'dashed' | 'dotted' | 'none'	'solid'	다음 항목으로 이어지는 선을 어떻게 그릴지. 선은 도착점이 아니라 출발한 단계의 것이므로, 그 단계에 도달했는지에 따라 색이 정해집니다
children	ReactNode	—	단계의 본문

예시

bullet

bullet에는 어떤 node든 넣을 수 있습니다. 번호는 사용자를 안내하는 절차에, 아이콘은 이미 일어난 사건에 어울립니다. 생략하면 원이 그려집니다.

세 상태는 각각 다른 모양을 씁니다. complete는 채워진 원, current는 후광이 둘린 채워진 원, upcoming은 빈 원입니다. 색을 구분하지 못해도 상태가 전달됩니다.

import { Timeline, TimelineItem } from 'neba';

function CheckIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none">
      <path
        d="m3.5 8.5 3 3 6-6"
        stroke="currentColor"
        strokeWidth="2"
        strokeLinecap="round"
        strokeLinejoin="round"
      />
    </svg>
  );
}

export default function TimelineBullets() {
  return (
    <div className="flex w-full max-w-md flex-col gap-8">
      {/* Numbers, for a sequence somebody is being walked through. */}
      <Timeline active={1} size="lg">
        <TimelineItem bullet="1" title="Account">
          Email and a password.
        </TimelineItem>
        <TimelineItem bullet="2" title="Workspace">
          Name it and pick a region.
        </TimelineItem>
        <TimelineItem bullet="3" title="Invite">
          Optional, and skippable.
        </TimelineItem>
      </Timeline>

      {/* Icons, for a sequence that already happened. */}
      <Timeline active={2} color="success" size="lg">
        <TimelineItem bullet={<CheckIcon />} title="Built" meta="1m 12s" />
        <TimelineItem bullet={<CheckIcon />} title="Tested" meta="3m 40s" />
        <TimelineItem title="Deploying" meta="running" />
      </Timeline>
    </div>
  );
}

status와 color

active는 정상적으로 진행되는 순서를 표현합니다. 실패해서 멈춘 단계처럼 인덱스로 설명할 수 없는 상태는 항목별 status와 color로 덮어씁니다.

connector는 다음 항목으로 이어지는 선의 모양입니다. 선은 도착점이 아니라 출발한 단계에 속하므로 그 단계의 상태에 따라 색이 정해집니다. none은 선을 없애서 한 Timeline 안에서 그룹을 나눌 때 씁니다.

import { Timeline, TimelineItem } from 'neba';

/**
 * `active` describes a sequence that is going to plan. A step that failed and
 * stopped it is not something an index can say, which is what the per-item
 * `status` and `color` overrides are for.
 */
export default function TimelineStatus() {
  return (
    <div className="w-full max-w-md">
      <Timeline active={2}>
        <TimelineItem title="Queued" meta="09:31">
          Picked up by the runner.
        </TimelineItem>
        <TimelineItem title="Built" meta="09:33" connector="dashed">
          Artifacts uploaded.
        </TimelineItem>
        <TimelineItem title="Tests failed" meta="09:36" color="danger" status="current">
          3 of 412 assertions did not pass.
        </TimelineItem>
        <TimelineItem title="Deploy" status="upcoming">
          Blocked until the tests pass.
        </TimelineItem>
      </Timeline>
    </div>
  );
}

orientation

horizontal은 결제 화면 상단의 stepper 형태입니다. 단계 수와 라벨 길이에 여유가 없으므로 짧은 라벨에만 적합합니다.

import { Timeline, TimelineItem } from 'neba';

export default function TimelineHorizontal() {
  return (
    <div className="w-full max-w-2xl">
      <Timeline orientation="horizontal" active={1} density="compact">
        <TimelineItem bullet="1" title="Cart" meta="3 items" />
        <TimelineItem bullet="2" title="Delivery" meta="Address" />
        <TimelineItem bullet="3" title="Payment" meta="Card" />
        <TimelineItem bullet="4" title="Done" />
      </Timeline>
    </div>
  );
}

접근성

• <ol>로 렌더링되므로 순서가 있는 목록으로 읽힙니다.
• current 상태의 항목에는 aria-current="step"이 붙습니다.

이럴 때는 다른 컴포넌트를

• 지난 기록이 아니라 현재 진행률을 보여 준다면 ProgressLinear를 쓰세요.
• 순서에 의미가 없는 나열이라면 List를 쓰세요. Timeline의 선은 "그다음"이라는 의미를 갖습니다.