# Agenda View

The coming days' events as a scrolling list.

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

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

import * as React from "react";
import { addWeeks } from "date-fns";

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

export function AgendaViewDemo() {
  // The provider reads its initial events once, so create them once: this
  // week's and next week's (with their own ids), so the list runs past today
  const [initialEvents] = React.useState(() => {
    const today = new Date();
    const nextWeek = createSampleEvents(addWeeks(today, 1)).map((event) => ({
      ...event,
      id: `${event.id}-next`,
    }));
    return [...createSampleEvents(today), ...nextWeek];
  });

  return (
    <CalendarProvider defaultEvents={initialEvents}>
      <AgendaView />
    </CalendarProvider>
  );
}
```

Agenda View lists the events of the next 30 days, grouped by day. Days without events are skipped, except today, which always shows with its date in a badge and a line at the current time. It reads its state from the surrounding [`CalendarProvider`](/docs/components/calendar-core) like every view, and fits phones better than a time grid: there's no grid to squeeze, only rows.

## Installation

```bash
npx shadcn add @calendarcn/agenda-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 lucide-react`
3. Copy these files into your project, keeping the paths under your components, hooks and lib folders:
   - [`components/agenda-view.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/agenda-view.tsx)

## Usage

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

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

Rendered on its own, it sets the provider's view to `"agenda"` and starts on today. Previous and next move by 30 days, and the provider's `monthName` and `year` name the month the list starts in. To switch between the agenda and other views, render the view the provider is on, as the [Calendar](/docs/components/calendar) example does. Switching to the agenda starts it on today when the period on screen contains today, and on that period's first day otherwise.

## Features

- Each day lists its all-day events first, then timed events by start time.
- An event that spans several days shows under each of them with "Day 2 of 3". A timed one reads "From 4 PM" on its first day, "All day" in between and "Until 1 PM" on its last.
- Click an event, or press `Enter` on it, to select it and open the same details popover as the other views, below the row. [`renderEventDetails`](/docs/components/event-details#custom-details) replaces its body. Right-click opens the event's context menu.
- [`renderEventContent`](/docs/components/calendar-core#custom-event-content) draws the inside of each row, with `placement: "agenda"`.
- Times follow the provider's `hourCycle`, and day and month names its `locale`. Hiding weekends in the view settings hides their days here too. With week numbers on, "Week 23" marks where each week starts, and with declined events hidden the events you declined aren't listed.
- Rows stack the title over the time on narrow screens, and line up time, title and location in columns once the agenda is wider than 36rem. It's a container query, so it follows the agenda's own width.
- Past events are faded. A friendly empty state shows when no event falls in the 30 days.
- Move a focused event a day with `Alt+←` / `Alt+→`, or a `snapMinutes` step with `Alt+↑` / `Alt+↓`. See [Keyboard & accessibility](/docs/components/calendar#keyboard--accessibility).

> **Details on phones**
>
> A 320px popover leaves little of a phone screen. The [live demo](/) turns it
> off with `showEventPopover={false}` and opens the details in a sheet from
> `onEventSelect` instead.

## API Reference

### AgendaView

Everything else (date, events, 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 below its row. Turn it off when the details are shown elsewhere, such as a side panel or a sheet. |
| `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. |
