Timeline

시간 순서에 따라 항목을 카드 형태로 표시하는 타임라인 컴포넌트입니다.

개요

Timeline 컴포넌트는 Collapsible 영역 안에 시간순 카드 목록을 표시하며, 무한 스크롤로 추가 데이터를 로드할 수 있습니다.

주요 특징

✅ 시간순 카드: 각 항목을 날짜·제목·내용 구조의 카드로 표시
✅ 접기/펼치기: Collapsible 영역으로 콘텐츠 접기·펼치기 지원
✅ 무한 스크롤: 스크롤 하단 도달 시 onLoadMore 콜백으로 추가 데이터 로드
✅ 로딩 상태: loading prop으로 로딩 오버레이 표시
✅ 빈 데이터 상태: 데이터가 없을 때 안내 메시지 표시
✅ 영역별 스타일: timestampStyle, titleStyle, contentStyle로 커스터마이징

기본 사용

<Timeline>에 title과 items 배열을 전달합니다.

Code


import { Timeline } from "@vortex/ui-cals"
 
const items = [
  { timestamp: "2025-06-20 14:30", title: "배포 완료", content: "v1.19.0 프로덕션 배포가 완료되었습니다." },
  { timestamp: "2025-06-18 10:00", title: "QA 통과", content: "모든 테스트 케이스가 통과되었습니다." },
  { timestamp: "2025-06-15 09:00", title: "개발 착수", content: "Timeline 컴포넌트 개발을 시작했습니다." },
]
 
<Timeline title="프로젝트 이력" items={items} />

빈 데이터 상태

items가 빈 배열이면 emptyText가 표시됩니다.


<Timeline title="빈 타임라인" items={[]} emptyText="조회 결과가 없습니다" />

로딩 상태

loading prop으로 로딩 인디케이터를 표시합니다.


<Timeline title="로딩 중" items={items} loading />

접기/펼치기

defaultCollapsed로 초기 접힘 상태를, collapseDisabled로 접기 잠금을 설정합니다.


{/* 초기 접힘 */}
<Timeline title="기본 접힘" items={items} defaultCollapsed />
 
{/* 접기 잠금 (항상 열림) */}
<Timeline title="접기 잠금" items={items} collapseDisabled />

무한 스크롤

onLoadMore와 hasMore를 사용하여 스크롤 하단 도달 시 추가 데이터를 로드합니다.


const [items, setItems] = useState(initialItems)
const [hasMore, setHasMore] = useState(true)
 
<Timeline
  title="무한 스크롤"
  items={items}
  hasMore={hasMore}
  onLoadMore={() => {
    fetchMore().then((newItems) => {
      setItems((prev) => [...prev, ...newItems])
      if (newItems.length === 0) setHasMore(false)
    })
  }}
  height="300px"
/>

영역별 스타일

timestampStyle, titleStyle, contentStyle로 각 영역의 폰트·색상을 커스터마이징합니다.


<Timeline
  title="커스텀 스타일"
  items={items}
  timestampStyle={{ color: "#6366f1", fontWeight: "bold" }}
  titleStyle={{ color: "#0f172a", fontSize: "1rem" }}
  contentStyle={{ fontStyle: "italic", color: "#64748b" }}
/>

API Reference

Props

Prop	Type	Default	Description
`title`	`string`	-	Collapsible 헤더에 표시할 제목
`items`	`TimelineItem[]`	`[]`	타임라인 데이터 배열
`loading`	`boolean`	`false`	로딩 상태 표시
`hasMore`	`boolean`	`false`	추가 데이터 존재 여부 (false면 무한 스크롤 중단)
`pageSize`	`number`	`10`	한 번에 로드할 데이터 수 (정보성)
`collapseDisabled`	`boolean`	`false`	접기/펼치기 잠금
`defaultCollapsed`	`boolean`	`false`	초기 접힘 상태 (true=닫힘)
`fullSize`	`boolean`	`false`	부모 컨테이너 크기에 맞춤
`visible`	`boolean`	`true`	표시 여부 (false → 렌더 안 함)
`height`	`string \| number`	`'250px'`	스크롤 영역 높이
`emptyText`	`string`	`'데이터가 없습니다'`	빈 상태 텍스트
`backgroundColor`	`string`	-	콘텐츠 영역 배경색
`timestampStyle`	`CSSProperties`	-	날짜 영역 스타일
`titleStyle`	`CSSProperties`	-	제목 영역 스타일
`contentStyle`	`CSSProperties`	-	내용 영역 스타일
`onLoadMore`	`() => void`	-	스크롤 하단 도달 시 추가 데이터 로드 콜백
`className`	`string`	-	컨테이너 CSS 클래스
`style`	`CSSProperties`	-	인라인 스타일

TimelineItem

Field	Type	Required	Description
`timestamp`	`string`	✅	날짜/시간 문자열
`title`	`string`	✅	제목
`content`	`string`	✅	내용

접근성

권장 사항

✅ 타임라인 항목이 ol > li 시맨틱 마크업으로 렌더링
✅ Foundation Collapsible 활용으로 키보드 접근성(Enter/Space) 자동 지원
✅ 접기/펼치기 트리거에 aria-expanded 자동 적용