# Week calendar

> A full calendar app with a week grid. Drag to create, move and resize events, answer invites right on the grid, and overlay teammates' calendars from a side panel with a mini month and the next meeting. Pages for invites and booking links complete the app.

- Type: Screen (a complete app view, installed as a block)
- Page: https://uiarc.dev/components/screens/week-calendar
- Markdown: https://uiarc.dev/components/screens/week-calendar/markdown

- Access: Arc Pro
- Registry id: `week-calendar`
- Source file: `registry/blocks/week-calendar/week-calendar.tsx`
- Built from: Motion
- Keywords: react calendar app, week calendar screen, drag and drop calendar, notion calendar clone, google calendar clone, meeting invites rsvp, booking links, app screen

Use this for scheduling and planning views. Pass your events and calendars, and persist changes in onCreate, onUpdate, and onDelete.

## When to use

- A complete calendar product screen: week planning, invites to answer and booking links in one app.
- Scheduling tools where people create, move and resize time blocks and overlay teammates' calendars.

## When not to use

- Use month-calendar for a month overview with events per day.
- Use calendar or date-picker to pick a date, and time-picker for a single time.
- Use availability-picker to collect open slots from someone.

## Installation

Week calendar is part of Arc Pro. The live preview is public; the source and install command need Pro.

### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/week-calendar
```

### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

## Usage

```tsx
import { useState } from "react";
import { WeekCalendar, type CalendarEvent } from "@/components/arc/blocks/week-calendar/week-calendar";

const calendars = [
  { id: "work", name: "Work", color: "sky", account: "you@company.com" },
  { id: "personal", name: "Personal", color: "green", account: "iCloud" },
  { id: "dana", name: "Dana Park", color: "orchid", account: "People", hidden: true, readOnly: true },
];

export default function CalendarPage({ initial }: { initial: CalendarEvent[] }) {
  const [events, setEvents] = useState(initial);
  return (
    <div style={{ height: "100dvh" }}>
      <WeekCalendar
        events={events}
        onEventsChange={setEvents}
        calendars={calendars}
        onCreate={event => api.create(event)}
        onUpdate={event => api.update(event)}
        onDelete={event => api.remove(event.id)}
        onRespond={(event, rsvp) => api.respond(event.id, rsvp)}
        timeZone="America/Los_Angeles"
      />
    </div>
  );
}
```

## API reference

### WeekCalendar

A full calendar app screen on the screen shell. The sidebar holds Calendar, Invites with a live count and Scheduling, a mini month to jump to any date, the calendars grouped by account with Arc checkboxes in each calendar's colour, a workspace switch with its own mark and an account menu that can start the week on Sunday. The calendar page is a week grid where you drag on empty time to draw an event and name it in a quick create popover, drag events between days and times, stretch the bottom edge to resize, and click an event to edit its title, time and calendar, answer the invite, copy the meeting link and see who is going; everything snaps to 15 minutes. An agenda panel, closed by default and opened from the header, holds the next meeting with its join link, the meetings after it and world clocks. Unanswered invites draw as outlines until you reply on the grid or on the invites page, and the scheduling page has booking links with copy and pause, upcoming bookings and weekly hours. Without events it shows a realistic week in November 2026.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `events` | `CalendarEvent[]` | – | Controlled events: { id, title, start: Date, end: Date, calendarId, allDay?, location?, attendees?, rsvp?, organizer?, conference?, description? }. Pair with onEventsChange. |
| `defaultEvents` | `CalendarEvent[]` | – | Starting events when uncontrolled. Without events or defaultEvents the screen shows the sample week from week-calendar-data.ts. |
| `onEventsChange` | `(events: CalendarEvent[]) => void` | – | Called with the full list after every change: create, move, resize, edit, answer, delete and undo. |
| `onCreate` | `(event: CalendarEvent) => void` | – | Called when someone saves a new event, and when an undo restores a deleted one. |
| `onUpdate` | `(event: CalendarEvent, previous: CalendarEvent) => void` | – | Called after a move, resize, edit or answer, with the event before the change. |
| `onDelete` | `(event: CalendarEvent) => void` | – | Called when an event is deleted. The undo toast calls onCreate if the person restores it. |
| `onRespond` | `(event: CalendarEvent, rsvp: "yes" \| "maybe" \| "no") => void` | – | Called when someone answers an invite, from the details popover or the invites page. |
| `calendars` | `CalendarSource[]` | `SAMPLE_CALENDARS` | Calendars as { id, name, color, hidden?, account?, avatar?, icon?, readOnly? }. color is blue, sky, green, violet, orchid, amber, rose, teal (Arc tone tokens) or any CSS color. account groups the sidebar list (an email shows the Google mark, "iCloud" the Apple mark); icon is a lucide icon that marks the calendar in pickers, tinted with its colour; readOnly calendars, such as a teammate's, can be shown but not written to. |
| `defaultDate` | `Date` | – | The day to open on. Defaults to today, or to the sample week when showing sample events. |
| `defaultView` | `"week" \| "workweek" \| "day" \| "3day" \| "agenda"` | `"week"` | Starting view. Below a 640px grid, week views show three days and agenda replaces work week. |
| `defaultPage` | `"calendar" \| "invites" \| "scheduling"` | `"calendar"` | The page the screen opens on. |
| `onViewChange` | `(view: CalendarView) => void` | – | Called when the view changes. |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | First day of the week; 0 is Sunday. The account menu switches between Monday and Sunday. |
| `startHour` | `number` | `0` | First hour shown in the day grid. |
| `endHour` | `number` | `24` | Hour the day grid ends at. |
| `timeZone` | `string` | – | IANA zone the grid runs in, such as "America/New_York". Defaults to the browser's zone. |
| `locale` | `string` | `"en-US"` | Locale for dates and times. |
| `className` | `string` | – | Class for the root. The screen fills its parent, so give the parent a height. |

### CalendarBoard

The calendar grid on its own, without the app shell: its own toolbar, an optional sidebar with a mini month and calendar toggles, and the same drag, keyboard and details behaviour. It takes the WeekCalendar event props, plus chrome="screen" to leave the toolbar to a host, a controlled hidden set, a controllerRef (previous, next, today, setView, newEvent, goToDay, openEvent) and onChromeChange for drawing an outside header.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `chrome` | `"standalone" \| "screen"` | `"standalone"` | standalone draws its own toolbar and sidebar; screen fills its parent and leaves them to a host. |
| `hidden` | `ReadonlySet<string>` | – | Controlled hidden calendar ids. Pair with onHiddenChange. |
| `controllerRef` | `Ref<CalendarController>` | – | Drives the board from outside: previous, next, today, setView, newEvent, goToDay and openEvent. |
| `onChromeChange` | `(chrome: CalendarChrome) => void` | – | Reports the title, month, view, available views, visible days, today and whether Today would move. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Cmd / Ctrl + K | Focuses the sidebar search, which filters the pages. |
| Arrow left / Arrow right | Moves between days; past the edge of the range, the next week or days slide in. |
| T | Goes to today. |
| N | Drafts a new event at the next free hour of the focused day and opens the quick create form. |
| Enter | Saves the quick create form, opens a focused event, or drafts an event on a focused day. |
| Delete / Backspace | Deletes the focused or selected event, with an undo toast. |
| Escape | Closes a popover or sheet, cancels a drag, or clears the selection. |
| D / W | Switches to the day or week view. |
| Arrow keys in the view switch | Change the view, like a tab list. |
| Arrow up / Arrow down | On an event, moves focus to the previous or next event; in the sidebar, moves between pages. |
| Alt + Arrow keys | Moves the focused event by a day or 15 minutes; add Shift with up and down to change its length. |
| Cmd / Ctrl + Z | Undoes the last move, resize, time change or delete. |

## Accessibility

- Each range is a role="grid" labelled with its dates and described by screen reader instructions; every day is a labelled grid cell with its date and event count, and keyboard focus moves between them with the arrow keys.
- Events are buttons whose labels read the title, date, time, calendar, location and whether the invite is unanswered or declined; outlines and strikethrough are never the only signal.
- The quick create form and event details are labelled dialogs that take focus, close on Escape or a press outside, and return focus to the event. The answer control and view switch are radio groups; calendar toggles are checkboxes and booking links and weekly hours use switches.
- Pages that are not shown are inert, so focus and screen readers only reach the current page. A polite live region announces range changes, creates, moves, answers, deletes and undos.

## Motion

- Ranges slide in the direction of travel on a spring without overshoot, and a swipe on touch drags the neighbors along so letting go continues without a seam.
- Events animate to new positions with transforms only: a dragged event hops between 15 minute slots, and neighbors settle into their new columns after a drop or an edit.
- Pages crossfade once; answered invites fold out of the waiting list and into answered; the view switch highlight glides for the pointer and lands instantly for keys. Hover fills are instant and buttons press to 0.97.
- Reduced motion replaces slides, folds and springs with instant changes and short fades.

## Responsive behavior

- At 1440 by 900 the sidebar with its mini month and calendars sits beside the full week grid; the 288px agenda panel opens from the header and can be resized.
- Below 1080px the agenda panel is a sheet; below 900px the sidebar is a sheet, picking a day in its month closes it, and the view switch moves to its own row.
- Below 640px of grid the week becomes three days with Day and Agenda views, swipes change days, and a long press starts creating or moving so vertical swipes still scroll. Invites and booking links stack their actions under the text.
- The screen fills its parent with no page scroll; the grid, the panel and each page scroll inside with hidden scrollbars and a fade at the cut edge.

## Performance

- Event blocks are memoized on primitive props, so a drag re-renders only the event that moves; position changes animate with transforms, never layout.
- Pages stay mounted under the current one, so switching keeps the week, the scroll position and local state without recomputing.
- All events are plain DOM; for thousands of events per week, pass only the visible range.

## Notes for AI

- Use as a complete calendar screen; give its parent a height. Use CalendarBoard when you only need the grid inside your own layout.
- Event times are Date instants shown in timeZone (or the browser's zone); store UTC. Set rsvp on events other people invited you to so they draw as outlines and appear on the invites page.
- Booking links, upcoming bookings and weekly hours on the scheduling page are local sample state in calendar-screen.tsx; copying links uses the clipboard and nothing is sent.
- sampleEvents() and SAMPLE_CALENDARS in week-calendar-data.ts are demo content to remove. People are seeded gradient avatars from lib/media.ts; the Google, Apple and Zoom marks are sample content.

## Related

- [Month calendar](https://uiarc.dev/components/screens/month-calendar/markdown): A complete calendar app in the Arc shell. It has a month grid with event chips and N more, plus a docked day panel showing busy time, guests, video links and free gaps you can block as focus time. You can filter by calendar or text, drag to reschedule or plan across days, and use the invitations, upcoming and teammate views.
- [Calendar](https://uiarc.dev/components/calendar/markdown): Browse dates in a clear, compact month view.
- [Date picker](https://uiarc.dev/components/date-picker/markdown): Choose a date without losing context.
- [Availability picker](https://uiarc.dev/components/blocks/availability-picker/markdown): Find a meeting time across people and see the choice come together.

## Guidance for AI tools

Blocks are complete, self-contained screens with sample data. Replace the sample data and connect the callbacks described above. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt