Timeline Section Component
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Timeline Section Component is a specialized UI module designed to display professional or project-based history in a structured, chronological format. It functions as a custom block within the Sanity-backed Portable Text fields of page and project documents. Its primary purpose is to render a collection of milestones organized into up to two parallel timelines, providing a visual representation of experience, project phases, or historical events.
Sources: sanity/schemas/documents/project.ts:121-124, sanity/schemas/documents/page.ts:77-80, sanity/schemas/objects/timeline.ts:11-12
Data Architecture and Schema
The component's data structure is hierarchical, starting from the timeline object which contains an array of timeline items. Each item consists of a title and a nested array of milestone objects.
The Timeline Object
The timeline object acts as the container. In the Sanity Studio, it is configured to allow a maximum of two timeline groups to be displayed side-by-side.
| Field | Type | Description |
|---|---|---|
items | Array | A collection of timeline groups (max 2). |
title | String | The heading for an individual timeline group. |
milestones | Array | A list of milestone objects within that group. |
Sources: sanity/schemas/objects/timeline.ts:8-44, sanity.types.ts:24-38
The Milestone Object
Milestones are the individual entries within a timeline. They capture specific points in time with associated metadata.
| Field | Type | Description |
|---|---|---|
title | String | The main label for the event (Required). |
description | String | A detailed text explanation of the milestone. |
duration | Object | Contains start and end ISO date strings. |
image | Image | A thumbnail icon or representative image. |
tags | Array | Categorization labels (e.g., "Contract", "Full-time"). |
Sources: sanity/schemas/objects/milestone.ts:6-45, types/index.ts:4-15
Component Structure and Logic
The frontend implementation is split into two main React components: TimelineSection and TimelineItem.
TimelineSection Component
This component serves as the layout wrapper. It iterates through the timelines provided by Sanity and maps them into responsive columns. It utilizes OptimisticSortOrder to handle real-time content reordering within the Sanity Presentation tool.
- Data Attribution: Uses
createDataAttributeto enable visual editing overlays. - Layout: Uses Tailwind CSS classes
flex-colfor mobile andmd:flex-rowfor desktop to stack or align timelines.
Sources: components/TimelineSection.tsx:18-62
TimelineItem Component
The TimelineItem handles the granular rendering of a single milestone. It calculates display years from the duration object and manages the visual "connector line" between items.
- Year Formatting: Extract
getFullYear()fromduration.startandduration.end. If no end date exists, it defaults to "Now". - Visual Connection: A vertical line (
w-px bg-gray-200) is rendered between items, which is hidden for the last item in a group using thegroup-last:hiddenutility.
Sources: components/TimelineItem.tsx:4-44
Visual Data Flow
The following diagram illustrates how data flows from the Sanity Content Lake through the schema definitions to the React components.
The diagram shows the hierarchical relationship where Documents contain Timelines, which in turn feed the React component tree.
Sources: components/TimelineSection.tsx:24-27, components/TimelineItem.tsx:6, sanity/schemas/objects/timeline.ts:11-12
Implementation Details
Duration Calculation
The component logic handles date strings by converting them to JavaScript Date objects to extract the year.
const startYear = duration?.start ? new Date(duration.start).getFullYear() : undefined
const endYear = duration?.end ? new Date(duration.end).getFullYear() : 'Now'
Sources: components/TimelineItem.tsx:8-9
Schema Relationships
The relationships between the various types are defined in the Sanity schema and reflected in the TypeScript types.
This diagram represents the maximum of two timeline groups and the recursive milestone structure.
Sources: sanity/schemas/objects/timeline.ts:13-14, sanity/schemas/objects/milestone.ts:47-64, sanity.types.ts:24-49
Conclusion
The Timeline Section Component provides a flexible and visually distinct way to present chronological data. By combining a strict Sanity schema (limiting items to 2) with a responsive React implementation, it ensures that professional histories remain legible across different device sizes while maintaining deep integration with Sanity's real-time editing features via data attributes and optimistic UI updates.