# Year View

Twelve months at a glance, with the days that have events marked.

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

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

import * as React from "react";

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

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

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

Year View shows the provider's year as twelve small month grids, like Google Calendar's year view (Notion Calendar has none). Today is marked in red and every day with events gets a dot under its number. Click a day, or press `Enter` on it, to open its week. Like every view, it reads its state from the surrounding [`CalendarProvider`](/docs/components/calendar-core).

## Installation

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

Or install it by hand:

1. Install the items it builds on: `@calendarcn/calendar-core`
2. Install the dependencies: `npm install date-fns react-day-picker@^9`
3. Copy these files into your project, keeping the paths under your components, hooks and lib folders:
   - [`components/year-view.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/year-view.tsx)

## Usage

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

export function YearPlan() {
  return (
    <CalendarProvider defaultView="year" defaultEvents={events}>
      {/* Year View fills its parent's height and scrolls inside it */}
      <div className="h-[600px]">
        <YearView />
      </div>
    </CalendarProvider>
  );
}
```

Set `defaultView="year"` (or control `view`) so the provider snaps the date, header and navigation to years: previous and next move a year, and `visibleRange` runs from January 1 to the next January 1. To switch between the year and the other views, see the [Calendar](/docs/components/calendar) example.

## Features

- A click on a day, or `Enter` or `Space` on a focused one, calls `showDay()`, which switches the provider to the week view and briefly highlights that day. Render [Week View](/docs/components/week-view) for it, as the Calendar block does, or pass `onDayClick` to do something else. With Year View alone and no `onDayClick`, the click has nothing to show.
- The arrow keys move between days, `Page Up` and `Page Down` by a month, `Home` and `End` to the ends of the week. They stop at the ends of the year. `J` and `K` change the year, and focus stays on the same day.
- Each month is a grid named by its month and year, and each day a button named by its date, "today" and its number of events, such as "Thursday, June 4, today, 3 events".
- The week start, the locale's month and weekday names, and week numbers come from the provider. With weekends hidden, each month drops its Saturday and Sunday columns, and the arrow keys, `Home` and `End` skip them.
- With declined events hidden, a day's count leaves out the events you declined.
- Months sit four to a row on wide screens, three on medium ones and two on phones.

## API Reference

### YearView

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

| Prop | Type | Description |
| --- | --- | --- |
| `onDayClick` | `(date: Date) => void` | Called when a day is clicked, or picked with Enter or Space. Defaults to the provider's `showDay()`, which opens the day's week. |
| `className` | `string` | Classes for the root element. |
