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.json

Preview

2027
2026
2025
2024
2023
2022
2021
2020
2019
2018
MSc CS
CTO@Scale-upJAN 25
JUL 24
Sabbatical
Founder@StartupJAN 23
AUG 21
Consultant @ Boutique
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

PropTypeDescription
eventsCalendarEvent[]Array of events to display (required)
classNamestringAdditional CSS classes
onEventClickfunctionCallback when an event is clicked

CalendarEvent

PropTypeDescription
idstringUnique identifier (required)
titlestringEvent title (required)
subtitlestringSecondary label
startDatestringStart date in YYYY-MM format (required)
endDatestringEnd date in YYYY-MM format (omit for ongoing)
descriptionstringEvent description
colorstringTailwind color classes for theming
variantdefault, compact, milestone, or breakCard visual variant
iconstringIcon or image URL

Variants

  • default - Standard card with full layout
  • compact - Narrow card with vertical text
  • milestone - 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