# Time Grid

The scrollable hour grid behind the day and week views.

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

```tsx title="src/examples/time-grid-demo.tsx"
"use client";

import * as React from "react";

import { CalendarProvider } from "@/components/calendar-provider";
import { TimeGrid } from "@/components/time-grid";
import { createSampleEvents } from "@/lib/sample-events";

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

  return (
    <CalendarProvider defaultEvents={initialEvents}>
      {/* A three-day grid: prev/next step by three days */}
      <TimeGrid view="week" numberOfDays={3} scrollToHour={8} />
    </CalendarProvider>
  );
}
```

The time grid lays out days as columns and hours as rows. [Day View](/docs/components/day-view) and [Week View](/docs/components/week-view) are both built on it, and you can use it directly for a custom layout.

## Installation

```bash
npx shadcn add @calendarcn/time-grid
```

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. Add the shadcn/ui components it uses: `npx shadcn add command kbd popover tooltip`
4. Copy these files into your project, keeping the paths under your components, hooks and lib folders:
   - [`components/time-grid.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/time-grid.tsx)
   - [`components/calendar-day-headers.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/calendar-day-headers.tsx)
   - [`components/week-view-all-day-row.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/week-view-all-day-row.tsx)
   - [`components/week-view-grid.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/week-view-grid.tsx)
   - [`components/week-view-time-axis.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/week-view-time-axis.tsx)
   - [`components/week-view-time-indicator.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/week-view-time-indicator.tsx)
   - [`components/week-view-people.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/week-view-people.tsx)
   - [`components/time-zone-axis-label.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/time-zone-axis-label.tsx)
   - [`components/time-zone-list.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/time-zone-list.tsx)
   - [`components/availability-layer.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/availability-layer.tsx)
   - [`hooks/use-all-day-resize.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-all-day-resize.ts)
   - [`hooks/use-event-drag.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-event-drag.ts)
   - [`hooks/use-event-draw.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-event-draw.ts)
   - [`hooks/use-event-resize.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-event-resize.ts)
   - [`hooks/use-horizontal-scroll.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-horizontal-scroll.ts)
   - [`hooks/use-media-query.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-media-query.ts)

## Features

- A time axis, a column per day and a current-time indicator.
- An all-day row for all-day and multi-day events.
- Overlapping events placed side by side.
- Drag an event to move it, including to another day. The grid scrolls when you reach its edge.
- Drag the top or bottom edge of an event to resize it.
- Double-click an empty slot to create an event, or press and drag to draw one, as in Notion Calendar. The all-day row does the same for all-day events. See [Creating events](/docs/components/calendar-core#creating-events).
- Visible hours, snap step and clock come from [`CalendarProvider`](/docs/components/calendar-core#calendarprovider): `dayStartHour`, `dayEndHour`, `snapMinutes` and `hourCycle`.
- Additional time zones' hours beside the time axis, from the provider's [`secondaryTimeZones`](/docs/components/calendar-core#additional-time-zones). Each zone's label opens Notion Calendar's menu for it (change, make primary or secondary, remove), and the "+" left of "All-day" adds one.
- The calendar's own zone, [`timeZone`](/docs/components/calendar-core#time-zone), labels the time axis, and a zone travelled to is filled in the primary color with an x that travels back home.
- The provider's [view settings](/docs/components/calendar-core#view-settings): with weekends hidden the columns are weekdays only, so scrolling, previous and next, and a drag from Friday to the next column all step over the weekend to Monday. Declined events are struck through on a dashed outline, or hidden.
- Other people's events behind yours, hatched in their color, and the free time you share highlighted, while you meet with them or show their calendar: see [Meeting with people](/docs/components/calendar-core#meeting-with-people).
- Hours that fill the screen by default, or the provider's [`hourHeight`](/docs/components/calendar-core#hour-size), which zooming steps through while the middle of the screen stays put.

## Usage

```tsx
import { CalendarProvider } from "@/components/calendar-provider";
import { TimeGrid } from "@/components/time-grid";

export function ThreeDays() {
  return (
    <CalendarProvider defaultEvents={events}>
      <div className="h-[600px]">
        <TimeGrid view="week" numberOfDays={3} />
      </div>
    </CalendarProvider>
  );
}
```

## API Reference

### TimeGrid

Use it directly when you switch between day and week yourself and want to keep the scroll position, as the [demo](/) does. Everything else is set on [`CalendarProvider`](/docs/components/calendar-core#calendarprovider).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `view` (required) | `"day" \| "week"` | – | "day" shows one column, "week" shows `numberOfDays` columns. While the provider's `view` is uncontrolled, the provider adopts it, so navigation and header info follow it. |
| `numberOfDays` | `number` | – | Number of day columns. Defaults to the provider's `numberOfDays`. When set, it fixes the column count, and prev/next step by it below 7 while the provider's `numberOfDays` is uncontrolled. |
| `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. |
| `scrollToHour` | `number` | – | Hour the grid scrolls to when it mounts, e.g. `8` for 8 AM or `8.5` for 8:30. Applied once and clamped to the provider's `dayStartHour`..`dayEndHour`. Unset starts at the top. |
| `className` | `string` | – | Classes for the root element. |
