Views

trud-calendar comes with four built-in views:

type CalendarView = "month" | "week" | "day" | "agenda";

Month view

A 6-week grid showing the full month context. Features:

• Event pills with color indicators
• Multi-day event spanning across cells
• “+N more” popover — click to see all events for a day
• Drag & Drop — move events between days (preserves original time)
• Keyboard navigation — arrow keys to navigate between days, Enter/Space to activate

Week view

A 7-column time grid showing one week. Features:

• Overlap handling — column-packing algorithm positions overlapping events side by side
• All-day row — multi-day and all-day events displayed above the time grid
• Multi-day timed events — timed events spanning multiple days are segmented per day (e.g., a conference from Wed 10:00 to Fri 16:00 shows across all three days)
• Current time indicator — red line showing “now”
• Auto-scroll — scrolls to the current hour on mount
• Configurable hours — set dayStartHour and dayEndHour
• Drag & Drop — move events to any day/time slot (configurable snap)
• Resize — drag the top or bottom edge of events to change start time or duration
• Drag-to-create — drag across empty slots to select a time range
• Keyboard navigation — arrow keys to navigate, Enter/Space to activate

Day view

A single-column time grid — same engine as the week view, focused on one day. All week view features apply.

Agenda view

A chronological event list grouped by date. Features:

• Date section headers with sticky positioning
• Today highlight badge
• Empty state — shows a customizable “no events” message
• Time range display for timed events, “all-day” label for all-day events
• Keyboard navigation — Up/Down arrow keys between items, Enter/Space to click

Switching views

Use defaultView (uncontrolled) or view + onViewChange (controlled):

// Uncontrolled — starts on week view
<Calendar events={events} defaultView="week" />

// Controlled — you manage the view state
const [view, setView] = useState<CalendarView>("month");
<Calendar events={events} view={view} onViewChange={setView} />

Time grid customization

Limit the visible hours in the week and day views:

<Calendar
  events={events}
  dayStartHour={8}   // Start at 8 AM
  dayEndHour={20}    // End at 8 PM
/>

Flexible time limits

When flexibleSlotTimeLimits is enabled, the time grid automatically expands to show events that fall outside the configured dayStartHour/dayEndHour:

<Calendar
  events={events}
  dayStartHour={9}
  dayEndHour={17}
  flexibleSlotTimeLimits
/>

If an event starts at 7 AM, the grid expands to show from 7 AM instead of 9 AM.

Hidden days

Hide specific days of the week from all views using hiddenDays. This is useful for business calendars that don’t need weekends:

// Hide Saturday (6) and Sunday (0)
<Calendar
  events={events}
  hiddenDays={[0, 6]}
/>

Hidden days are removed from the month grid columns, the week view day columns, and the agenda view date groups. Events on hidden days are still included in the data — they’re just not displayed.

Highlighted dates

Visually accent specific dates (holidays, deadlines, etc.) using highlightedDates:

<Calendar
  events={events}
  highlightedDates={["2026-03-25", "2026-12-25", "2026-01-01"]}
/>

Highlighted dates get a subtle accent background in the month grid cells and week view column headers.

Week numbers

Show ISO week numbers alongside the month grid:

<Calendar events={events} showWeekNumbers />

Week numbers appear as a narrow column on the left side of the month view.

Valid date range

Restrict how far users can navigate with validRange. The prev/next buttons automatically disable when at bounds:

<Calendar
  events={events}
  validRange={{
    start: "2026-01-01",
    end: "2026-12-31",
  }}
/>

You can set only start, only end, or both.

Year view

A 12-month overview showing the entire year. Features:

• Event dots — days with events show a small indicator dot
• Click to navigate — clicking any day switches to the day view for that date
• Highlighted dates — highlightedDates styling applies in the year grid
• Responsive grid — 2 columns on mobile, 3 on tablet, 4 on desktop

<Calendar events={events} defaultView="year" />