Calendar View

The Calendar view displays your items on a monthly calendar grid based on their date fields. It is ideal for content calendars, event planning, sprint schedules, and any date-driven workflow.

Layout

• Items are placed on the calendar according to their date or timeline column value.
• Items appear as colored pills inside each day cell, using the group color for visual distinction.
• Today's date cell is highlighted with a primary-color ring and a filled circle around the day number.
• Days outside the current month are shown dimmed with a lighter background.
• The week starts on Monday (ISO 8601 convention), with columns labeled Mon through Sun.

How Dates Are Determined

The calendar automatically detects which field to use for item placement:

1. Date columns are checked first. If an item has a value in a "Date" type column (e.g., Due Date, Publish Date), that date is used.
2. Timeline columns are checked next. If no date column is found but a "Timeline" type column exists, the start date of the range is used for placement.
3. No date — items without any date or timeline value do not appear on the calendar grid.

Add a date column

If your items are not appearing on the calendar, make sure your board has at least one Date or Timeline column and that items have values set for it.

Navigating the Calendar

The toolbar above the calendar grid provides navigation controls:

• Left arrow — navigate to the previous month.
• Today button (with a calendar icon) — jump back to the current month.
• Right arrow — navigate to the next month.
• The current month and year are displayed as a label (e.g., "April 2026").
• An item count indicator on the right shows the total number of items on the board (e.g., "42 items").

Navigation state is managed client-side with React useState. Clicking Previous or Next shifts the displayed month by one. Clicking Today resets to the current month. The URL does not change during navigation — the current month is local view state.

Day Cell Behavior

Each day cell displays up to 3 item pills. If more than 3 items share the same date, a "+N more" indicator appears below the visible items.

Each pill shows:

• The item name (truncated to fit the cell width).
• The group color as the pill background.
• A hover effect (reduced opacity) to signal clickability.

Click any pill to open the Item Detail Panel on the right side, where you can view and edit all field values, comments, and activity.

Keyboard Interaction

Item pills are keyboard-accessible. Use Tab to focus a pill and press Enter or Space to open the item detail panel.

Empty and Error States

• No items — when the board has no items at all, a centered empty state with a calendar icon is displayed, along with the message "No items yet. Add items with date columns to see them on the calendar."
• Loading — a skeleton loader mimics the calendar grid layout (header row plus 5 rows of 7 cells) while board data is being fetched.
• Error — if the board data fails to load, an error state with a Retry button is shown.

Data Source

The calendar view fetches data using the same boards.getByProjectId tRPC query as the Board, Table, and Timeline views. This means all four views share a single source of truth. Changes made in one view (e.g., updating a date in Table view) are immediately reflected when you switch to the Calendar.

Filtering

Use the filter panel to show only specific statuses, assignees, or field values. This is useful for seeing only your tasks, or only tasks in a particular phase. Filters are applied client-side, so changes take effect instantly without a server roundtrip.

Month Display

The calendar header displays the current month and year in a large, readable format (e.g., "April 2026"). Below the header, the 7-column weekday labels (Mon through Sun) serve as column headers for the grid.

Each month displays 5 or 6 rows of days depending on the calendar layout. For example, a month that starts on Saturday will need 6 rows to show all dates, while a month that starts on Monday typically needs only 5.

Tips

Use group colors strategically

Since calendar pills use the group color, assigning distinct colors to your groups (e.g., red for "Blocked", green for "Done") makes it easy to scan the calendar for patterns at a glance.

Mobile behavior

On mobile devices, the calendar grid adjusts to the available screen width. Day cells become narrower but remain scrollable, so you can still view all items.

Item Detail Panel

Click any item pill to open the Item Detail Panel on the right. The panel displays all field values, comments, activity history, and file attachments. You can edit fields inline, add comments, and change the item's date — the calendar view updates immediately when you close the panel.

Working with the Calendar in Teams

Since the calendar shares the same data source as all other views, changes made in the calendar (via the detail panel) are visible in real time to other team members viewing the same board in any view. WebSocket synchronization ensures that date changes propagate instantly.

Performance Considerations

The calendar computes a Map<dateKey, items[]> for each day cell, which is rebuilt only when the board data changes (via useMemo). The date key uses the format "yyyy-MM-dd" for efficient O(1) lookups, making rendering fast even with hundreds of items.

The grid renders 5-6 week rows depending on the month, with each week row containing 7 day cells. Days outside the current month are included to fill complete weeks.

Best Practices

• Use the calendar for deadline tracking — due dates are the most natural fit for calendar placement.
• Assign group colors to visually distinguish item types at a glance (e.g., red for blockers, green for completed).
• Navigate with the Today button after scrolling through past or future months to quickly return to the current view.
• Combine with filters to show only your tasks or only tasks in a specific status, reducing visual clutter on busy months.

Troubleshooting

Problem	Solution
Items not appearing on calendar	Ensure items have a value in a Date or Timeline column. Items without dates are excluded.
Wrong date shown for an item	Check which date column the calendar is using. Date columns take priority over Timeline columns.
"+N more" overflow not clickable	The overflow indicator shows how many additional items exist on that date. Click any visible pill to open the detail panel, then navigate from there.
Calendar shows wrong week start	The calendar always starts on Monday (ISO 8601). This is not configurable.
Loading state persists	Check your network connection. The board data fetch may be failing silently. Click away and return to retry.

Accessibility

The calendar grid uses semantic HTML with role="button" and tabIndex attributes on item pills, making the calendar navigable by keyboard and screen reader. Each pill has an aria-label describing the item name (e.g., "View details for Fix login bug").

Next Steps

• Board View — manage items in a Kanban layout.
• Timeline View — see items on a Gantt-style horizontal axis.
• Creating Items — add new items to your board.