Calendar
A timeline calendar component for visualizing events over time. Features automatic overlap detection, flex-based column layout, and multiple card variants.
Installation
npx shadcn@latest add https://ui.collectivecreation.company/calendar.jsonPreview
2027
2026
2025
2024
2023
2022
2021
2020
2019
2018
MSc CS
CTO@Scale-upJAN 25
JUL 24
Founder@StartupJAN 23
AUG 21
Growth Marketing@FintechJAN 19
Product Manager@SaaSMAR 20
Usage
example.tsx
import { Calendar } from '@/components/ui/calendar'
import type { CalendarEvent } from '@/components/ui/calendar'
const events: CalendarEvent[] = [
{
id: 'growth',
title: 'Growth Marketing',
subtitle: 'Fintech startup',
startDate: '2019-01',
endDate: '2021-06',
variant: 'default',
},
{
id: 'graduation',
title: 'MSc Computer Science',
startDate: '2018-06',
variant: 'milestone',
},
]
export function MyPage() {
return (
<Calendar
events={events}
onEventClick={(event) => console.log(event.title)}
/>
)
}Composition
The calendar exports the main Calendar component and a CalendarSkeleton for loading states. Events are plain objects typed with CalendarEvent.
composition.tsx
import { Calendar } from '@/components/ui/calendar'
import { CalendarSkeleton } from '@/components/ui/calendar'
// Full calendar with events
<Calendar events={events} onEventClick={handleClick} />
// Loading state
<CalendarSkeleton yearCount={5} />
// Minimal event structure
const event: CalendarEvent = {
id: '1',
title: 'Software Engineer',
subtitle: 'Tech Corp',
startDate: '2020-01',
endDate: '2022-06',
variant: 'default',
}API Reference
Calendar
| Prop | Type | Description |
|---|---|---|
events | CalendarEvent[] | Array of events to display (required) |
className | string | Additional CSS classes |
onEventClick | function | Callback when an event is clicked |
CalendarEvent
| Prop | Type | Description |
|---|---|---|
id | string | Unique identifier (required) |
title | string | Event title (required) |
subtitle | string | Secondary label |
startDate | string | Start date in YYYY-MM format (required) |
endDate | string | End date in YYYY-MM format (omit for ongoing) |
description | string | Event description |
color | string | Tailwind color classes for theming |
variant | default, compact, milestone, or break | Card visual variant |
icon | string | Icon or image URL |
Variants
default- Standard card with full layoutcompact- Narrow card with vertical textmilestone- Single-point event (dot + label)break- Diagonal striped background
Customization
The calendar uses Tailwind CSS for all styling. You can customize the year lane height by editing the YEAR_HEIGHT_PX constant, card colors via the color prop on each event, and border radius, spacing, and typography through Tailwind classes.
Accessibility
- Event cards are clickable with keyboard support
- Icons include alt text
- Color is not the sole means of conveying information