feat(ui): add Timeline component #9188
Conversation
- Add Timeline component with multiple layout positions - Support left, right, and alternate positioning - Include icon support in markers - Add comprehensive documentation and examples Resolves shadcn-ui#949, shadcn-ui#2141, shadcn-ui#3584, shadcn-ui#6993 Addresses discussion shadcn-ui#4285
|
@kamja44 is attempting to deploy a commit to the shadcn-pro Team on Vercel. A member of the Team first needs to authorize it. |
Changes SummaryThis PR adds a new Timeline component to shadcn/ui v4, addressing long-standing community requests. The component provides a modular, composable architecture with multiple layout positions (left, right, alternate, center), marker variants (default, primary, success, warning, destructive), icon support, and full accessibility via semantic HTML and data-slot attributes. Type: feature Components Affected: Timeline, TimelineItem, TimelineMarker, TimelineContent, TimelineSpacer, TimelineTitle, TimelineDescription, TimelineTime, Registry Architecture Impact
Risk Areas: TimelineSpacer has an empty className by default - may need to have actual dimensions for layout to work correctly in center mode, Korean language comments in the generated registry JSON content could be unintentional or cause confusion for contributors, The TimelineItem children rendering assumes valid React elements which may silently skip non-element children, The connector line hiding relies on CSS selector [li:last-child_&]:hidden which may not work correctly if non-li elements are accidentally rendered Suggestions
Full review in progress... | Powered by diffray |
Review Summary
Validated 24 issues: 6 kept (critical bugs and significant quality issues), 18 filtered (low value, autogenerated file context, or inconsistent with project standards) Issues Found: 6📊 4 unique issue type(s) across 6 location(s) 📋 Full issue list (click to expand)🟠 HIGH - Reference to undefined variable 'item' (2 occurrences)Category: bug 📍 View all locations
Rule: 🟡 MEDIUM - Inconsistent import path for cn utility functionCategory: quality File: Description: The timeline.tsx component imports the Suggestion: Change line 6 from Confidence: 85% Rule: 🟡 MEDIUM - Timeline marker variants rely solely on color to convey statusCategory: quality File: Description: The TimelineMarker component uses different color variants (success, warning, destructive, primary) to convey semantic meaning, but color alone is insufficient for accessibility. Users with color blindness cannot distinguish between these states. Suggestion: Add aria-label to describe the status or include visually hidden text (sr-only) that describes each variant. Example: Confidence: 75% Rule: 🟡 MEDIUM - File-wide type checking disabled with @ts-nocheck (2 occurrences)Category: quality 📍 View all locations
Rule: Powered by diffray - Multi-Agent Code Review Agent |
- Add ARIA roles: role="list", role="listitem", role="status" - Add aria-label with variant-based labels (Event, Important, Completed, Warning, Error) - Add sr-only text for screen reader support - Fix import path: @/registry/new-york-v4/lib/utils -> @/lib/utils - Improve color contrast: text-background -> text-current, bg-background -> bg-current - Add text-destructive-foreground to destructive variant - Add TimelineSpacer dimensions: min-w-0 flex-1 - Remove Korean comments and translate to English
✅ Resolved Issues1. ARIA roles for improved screen reader support
2. Timeline marker variants rely solely on color
3. Inconsistent import path for cn utility
4. TimelineSpacer dimensions
5. Korean language comments
|
Changes SummaryThis PR adds a new Timeline component to shadcn/ui v4, implementing a highly-requested feature (combined ~400 upvotes across related issues). The component provides a composable timeline with multiple layout positions (left, right, alternate, center), variant markers with icon support, and proper accessibility via ARIA attributes and semantic HTML. Type: feature Components Affected: Timeline (new component), TimelineItem, TimelineMarker, TimelineContent, TimelineSpacer, TimelineTitle, TimelineDescription, TimelineTime, Registry (updated with new component entries) Architecture Impact
Risk Areas: Auto-generated registry files (elevenlabs.json and other JSON files) included in the commit may be unintentional side effects of registry:build, TimelineMarker uses role='status' which may need validation for correct semantic usage in timeline context, Center position layout requires manual use of TimelineSpacer for proper alignment - could be error-prone for users Suggestions
Full review in progress... | Powered by diffray |
|
|
||
| Timeline with a centered vertical line and content alternating on both sides. Perfect for project roadmaps and process flows. | ||
|
|
There was a problem hiding this comment.
🟡 MEDIUM - Center Position description missing critical detail
Category: docs
Description:
Documentation states center position has alternating content but doesn't explain that users must manually order TimelineContent, TimelineMarker, and TimelineSpacer components.
Suggestion:
Add clarification: 'In center position, manually arrange TimelineContent, TimelineMarker, and TimelineSpacer to control which side content appears on.'
Confidence: 75%
Rule: ts_jsdoc_capability_claim_false
There was a problem hiding this comment.
The documentation now explicitly explains that in center position, users need to manually arrange TimelineContent, TimelineMarker, and TimelineSpacer components to control which side the content appears on:
In center position, manually arrange
TimelineContent,TimelineMarker, andTimelineSpacerto control which side content appears on. Place content before the marker for left-side display, or after the marker (withTimelineSpacerfirst) for right-side display.
This should make it much clearer for users how to use the center position layout.
| {/* Left side content */} | ||
| <TimelineItem> | ||
| <TimelineContent> | ||
| <TimelineTitle>Step 1</TimelineTitle> | ||
| <TimelineDescription>Content on the left</TimelineDescription> | ||
| </TimelineContent> | ||
| <TimelineMarker /> | ||
| <TimelineSpacer /> | ||
| </TimelineItem> |
There was a problem hiding this comment.
🔵 LOW - Center position example comment could be clearer
Category: docs
Description:
Comment says 'Left side content' but content has right-aligned text (text-right class for even index). Grid position is left but text alignment is right.
Suggestion:
Change comment to '/* Left column, right-aligned text */' or explain the distinction between grid position and text alignment.
Confidence: 65%
Rule: ts_jsdoc_example_wrong
There was a problem hiding this comment.
Fixed in the latest commit! I've updated the comments to clarify both the grid position and text alignment direction:
{/* Left column - text is right-aligned towards the center line */}{/* Right column - text is left-aligned towards the center line */}
This makes it clear that:
- The grid position (left/right column)
- The text alignment (aligned towards the center line)
are two separate aspects of the layout.
Review Summary
Validated 34 issues: 6 kept, 28 filtered Issues Found: 6See 2 individual line comment(s) for details. 📋 Full issue list (click to expand)🔴 CRITICAL - Reference to undefined variable 'item' in closureCategory: bug File: Description: The React.lazy callback references an undefined variable 'item' which does not exist in the closure scope. This pattern repeats 437 times throughout the file. The variable 'item' is not defined anywhere, causing ReferenceError at runtime when lazy component loads. Suggestion: The 'item' variable should be replaced with the actual object that contains the 'name' property. Since this is an auto-generated file (noted in the header), the build script at scripts/build-registry.ts needs to be fixed to generate the correct variable reference, or use a literal string like 'accordion' for each component. Confidence: 98% Rule: 🟡 MEDIUM - Duplicate aria-label and sr-only textCategory: quality File: Description: TimelineMarker has both aria-label (line 185) and sr-only span (line 201) providing identical text from variantLabels, causing redundant screen reader announcements. Suggestion: Remove either the aria-label attribute or the sr-only span to avoid duplicate announcements. Confidence: 85% Rule: 🟡 MEDIUM - Center Position description missing critical detailCategory: docs File: Description: Documentation states center position has alternating content but doesn't explain that users must manually order TimelineContent, TimelineMarker, and TimelineSpacer components. Suggestion: Add clarification: 'In center position, manually arrange TimelineContent, TimelineMarker, and TimelineSpacer to control which side content appears on.' Confidence: 75% Rule: 🔵 LOW - Inconsistent null coalescing operatorsCategory: quality File: Description: Line 172 uses 'variant || "default"' while line 201 uses 'variant ?? "default"'. Minor inconsistency - both work correctly since variant is typed and empty string is not a valid value. Suggestion: Use '??' consistently for proper null/undefined checking: 'variantLabels[variant ?? "default"]' Confidence: 65% Rule: 🔵 LOW - Center position example comment could be clearerCategory: docs File: Description: Comment says 'Left side content' but content has right-aligned text (text-right class for even index). Grid position is left but text alignment is right. Suggestion: Change comment to '/* Left column, right-aligned text */' or explain the distinction between grid position and text alignment. Confidence: 65% Rule: 🔵 LOW - React.Children.map returns unmodified non-elementsCategory: quality File: Description: Non-element children (null, undefined, strings) pass through without TimelineItemContext.Provider wrapping, which is intentional but could be documented. Suggestion: Add a comment explaining that non-element children are passed through intentionally, or use React.Children.toArray() with filtering for clearer intent. Confidence: 60% Rule: Powered by diffray - Multi-Agent Code Review Agent |
2 participants
Overview
This PR adds a new Timeline component to shadcn/ui v4, addressing long-standing community requests for a timeline component.
Related Issues & Discussions
This PR resolves/addresses:
Features
The Timeline component provides:
Component Structure
Added Files
UI Component
apps/v4/registry/new-york-v4/ui/timeline.tsxapps/v4/registry/new-york-v4/ui/_registry.ts (updated)Examples
apps/v4/registry/new-york-v4/examples/timeline-demo.tsxapps/v4/registry/new-york-v4/examples/timeline-with-icons.tsxapps/v4/registry/new-york-v4/examples/timeline-right.tsxapps/v4/registry/new-york-v4/examples/timeline-alternate.tsx (or timeline-center.tsx)apps/v4/registry/new-york-v4/examples/_registry.ts (updated)Documentation
apps/v4/content/docs/components/timeline.mdxScreenshots
Basic Timeline (Left Position)
Implementation Details
class-variance-authority(CVA) for variant managementChecklist
[O] Follows shadcn/ui design patterns and conventions
[O] Uses data-slot attributes for semantic styling
[O] Integrates with OKLCH color system
[O] Includes comprehensive documentation with examples
[O] All examples render correctly
[O] TypeScript types are properly defined
[O] Component is fully accessible
[O] Works with both light and dark themes
[O] Tested in development environment
Testing
Tested locally with:
pnpm registry:buildpnpm --filter=v4 devAll examples render correctly at
http://localhost:4000/docs/components/timeline