---
name: calendar
description: Design and layout guide for Calendar components. Focus on responsive constraints and proper container usage.
color: teal
---

# Calendar Design & Layout Guide

## 🚨 Critical Constraints

### 1. No Horizontal Overflow

The Calendar MUST NEVER cause horizontal scrolling. Test at 375px viewport width.

- The component handles internal overflow, but parent containers can break this
- Always use `min-w-0` in flex containers
- Never use fixed widths that exceed mobile viewport

### 2. Built-in View Toggle

The Calendar includes its own Month/Week/Day/Agenda toolbar. **Do not add external view toggle controls** - they are redundant and create confusion.

Use the `views` prop to control which views are available, and `defaultView` to set the initial view.

### 3. Height Control Only

The `size` prop controls HEIGHT only:

- `small`: 384px
- `medium`: 600px (default)
- `large`: 800px
- `full`: 100% of parent

Width is always 100% of the parent container.

## Layout Patterns

### Flex Containers

Always include `min-w-0` to prevent flex items from overflowing:

```
flex-1 min-w-0  ✅
flex-1          ❌ (can overflow)
```

### Grid Containers

Use `min-w-0` on grid cells containing calendars:

```
lg:col-span-2 min-w-0  ✅
lg:col-span-2          ❌ (can overflow)
```

### Full-Height Layouts

For calendars that fill available height, use `size="full"` with proper parent constraints:

```
Parent: h-screen or flex-1 min-h-0
Calendar: size="full"
```

## Mobile Considerations

### Recommended Mobile Views

On mobile devices (< 768px), consider limiting views to simpler options:

- Day view - single column, easy to read
- Agenda view - list format, no grid complexity

Month view works on mobile but cells are very compact.

### Mobile Container Pattern

For mobile-responsive templates, constrain width to viewport:

```
max-w-[calc(100vw-2rem)] md:max-w-full
```

This ensures content respects viewport width minus padding.

## Design Decisions

### When to Use Each View

| View   | Best For                               |
| ------ | -------------------------------------- |
| Month  | Overview, planning, seeing patterns    |
| Week   | Detailed scheduling, time blocks       |
| Day    | Focused single-day view, mobile        |
| Agenda | List of upcoming events, accessibility |

### Event Density

- Month view: Shows 2-3 events per cell, then "+X more"
- Week/Day view: Shows all events with time slots
- Agenda view: Shows all events in list format

### Custom Event Styling

Use `eventPropGetter` to color-code events by type, status, or category. Keep colors accessible and consistent with your design system.

## Key Rules Summary

1. **No x-axis overflow** - Test at 375px
2. **No external view toggles** - Built into component
3. **Always use `min-w-0`** - In flex/grid containers
4. **Use Date objects** - Never string dates
5. **Provide localizer** - Required for rendering
6. **Test on mobile** - Verify no horizontal scroll

## See Also

- `src/components/calendar/README.md` - Detailed API docs and code examples
- `src/components/calendar/calendar.stories.tsx` - Interactive examples