# Month View

A month at a glance.

Live example, interactive at https://calendarcn.xyz/docs/components/month-view. Its source:

```tsx title="src/examples/month-view-demo.tsx"
"use client";

import * as React from "react";

import { CalendarProvider } from "@/components/calendar-provider";
import { MonthView } from "@/components/month-view";
import { createSampleEvents } from "@/lib/sample-events";

export function MonthViewDemo() {
  // The provider reads its initial events once, so create them once
  const [initialEvents] = React.useState(() => createSampleEvents(new Date()));

  return (
    <CalendarProvider defaultView="month" defaultEvents={initialEvents}>
      <MonthView />
    </CalendarProvider>
  );
}
```

Month View shows six weeks at a time. Timed events are listed in each day, all-day and multi-day events run across days as bars, and busy days collapse the rest into a "more" button. Like every view, it reads its state from the surrounding [`CalendarProvider`](/docs/components/calendar-core).

## Installation

```bash
npx shadcn add @calendarcn/month-view
```

Or install it by hand:

1. Install the items it builds on: `@calendarcn/calendar-core`, `@calendarcn/event-details`
2. Install the dependencies: `npm install date-fns`
3. Copy these files into your project, keeping the paths under your components, hooks and lib folders:
   - [`components/month-view.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/month-view.tsx)
   - [`components/month-view-grid.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/month-view-grid.tsx)
   - [`components/month-view-day-cell.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/month-view-day-cell.tsx)
   - [`components/month-view-event-bar.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/month-view-event-bar.tsx)
   - [`components/month-view-event-item.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/month-view-event-item.tsx)
   - [`hooks/use-month-event-drag.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-month-event-drag.ts)
   - [`hooks/use-month-event-resize.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-month-event-resize.ts)
   - [`hooks/use-media-query.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-media-query.ts)
   - [`hooks/use-vertical-scroll.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-vertical-scroll.ts)

## Usage

```tsx
import { CalendarProvider } from "@/components/calendar-provider";
import { MonthView } from "@/components/month-view";

export function MonthlyPlan() {
  return (
    <CalendarProvider defaultView="month" defaultEvents={events}>
      {/* Month View fills its parent's height */}
      <div className="h-[600px]">
        <MonthView />
      </div>
    </CalendarProvider>
  );
}
```

Set `defaultView="month"` (or control `view`) so the provider snaps the date, header and navigation to months. To switch between month and week, see the [Calendar](/docs/components/calendar) example.

## Features

- Drag an event to another day, or drag the ends of a bar to change its dates.
- Double-click a day's empty space to create an all-day event, or press and drag across days to draw one over them. See [Creating events](/docs/components/calendar-core#creating-events).
- "N more" on a busy day calls `showDay()`, which switches the provider to the week view and briefly highlights that day. Render [Week View](/docs/components/week-view) for that view, as the [Calendar](/docs/components/calendar) example does; with Month View alone the button has nothing to show.
- Scroll vertically to move through weeks. Scrolling snaps to the nearest week.
- Hide weekends, show week numbers or hide the events you declined through the provider's view settings. Declined events are struck through while they show.
- Move a focused event a day with `Alt+←` / `Alt+→`, or a week with `Alt+↑` / `Alt+↓`. See [Keyboard & accessibility](/docs/components/calendar#keyboard--accessibility).

> **Scrolling over the preview**
>
> Month View turns vertical wheel scrolling into week navigation, so the page
> doesn't scroll while the pointer is over it. Scroll beside the preview to move
> down the page.

## API Reference

### MonthView

Everything else (date, events, week start, locale, view settings) is set on [`CalendarProvider`](/docs/components/calendar-core#calendarprovider).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showEventPopover` | `boolean` | `true` | Whether the selected event opens a details popover beside it. Turn it off when the details are shown elsewhere, such as a side panel. |
| `onEventPopoverExpand` | `() => void` | – | Called by the popover's expand button, e.g. to move the details into a side panel. The button is hidden when this is not set. |
| `className` | `string` | – | Classes for the root element. |
