Week calendarPro

• Type: Block

• Page: https://ui.xzero.co.uk/components/blocks/week-calendar

• Markdown: https://ui.xzero.co.uk/components/blocks/week-calendar/markdown

• Access: Xzero Pro

• Registry id: week-calendar

• Source file: registry/blocks/week-calendar/week-calendar.tsx

• Built from: Motion

• Keywords: react week calendar, drag and drop calendar, google calendar clone, scheduler component, time blocking calendar, event scheduler, react calendar with time zones

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

When to use

• Scheduling and planning screens where people create, move and resize time blocks across a week.
• Team or personal calendars that need several color coded calendars, all day events and an agenda on phones.

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

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui-pro/week-calendar

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

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

const calendars = [
  { id: "work", name: "Work", color: "blue" },
  { id: "personal", name: "Personal", color: "green" },
];

export default function SchedulePage({ initial }: { initial: CalendarEvent[] }) {
  const [events, setEvents] = useState(initial);
  return (
    <WeekCalendar
      events={events}
      onEventsChange={setEvents}
      calendars={calendars}
      onCreate={event => api.create(event)}
      onUpdate={event => api.update(event)}
      onDelete={event => api.remove(event.id)}
      startHour={6}
      timeZone="America/Los_Angeles"
    />
  );
}

API reference

WeekCalendar

A week calendar at the level of a native app: week, work week and day views on wide screens, three days and an agenda list on phones, a mini month and calendar toggles in a sidebar when there is room, and an all day row that collapses when it fills up. 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, day, time and calendar; everything snaps to 15 minutes. Events can be controlled or uncontrolled; without events it shows a realistic sample week.

Prop	Type	Default	Description
events	CalendarEvent[]	–	Controlled events: { id, title, start: Date, end: Date, calendarId, allDay?, location?, attendees? }. Pair with onEventsChange.
defaultEvents	CalendarEvent[]	–	Starting events when uncontrolled. Without events or defaultEvents the calendar 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, 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 or edit in the details popover, 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.
calendars	CalendarSource[]	SAMPLE_CALENDARS	Calendars as { id, name, color, hidden? }. color is blue, green, violet, amber, rose, teal or any CSS color; built in names are tuned for light and dark.
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 container week views show three days, and agenda is offered instead of work week.
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.
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". Times are converted and formatted with Intl. Defaults to the browser's zone.
locale	string	"en-US"	Locale for dates and times.
className	string	–	Class for the root element. Set --calendar-height on it to change the height of the scrolling grid.

Keyboard interactions

Keys	Action
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, cancels a drag, or clears the selection.
D / W	Switches to the day or week view.
Arrow up / Arrow down	On an event, moves focus to the previous or next event.
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, full date, start and end time, calendar and location; all day events and agenda rows follow the same pattern.
• 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.
• A polite live region announces range changes, creates, moves, resizes, deletes and undos. Pointer focus draws no ring; keyboard focus shows Xzero's shared focus ring. Focus shows the same fill as hover.

Motion

• Ranges slide in the direction of travel on a spring without overshoot, the header and all day row move with the grid, 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.
• Popovers scale in from the edge that faces their event; the undo toast rises from the bottom.
• Reduced motion replaces slides and position springs with instant moves and short fades.

Responsive behavior

• From a 1100px container a sidebar adds a mini month and calendar toggles; narrower, the toggles move into a Calendars popover.
• Between 640px and 900px the gutter and dates tighten and event blocks drop details that no longer fit, using container queries on each event.
• Below 640px the week becomes three days with Day and Agenda views, horizontal swipes change days, and a long press starts creating or moving so vertical swipes still scroll.
• The grid scrolls inside a height of clamp(480px, 72vh, 760px); set --calendar-height on the root to change it.

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.
• Time zone conversion runs once per events change; the now line updates on each minute boundary.
• All events are plain DOM; for thousands of events per week, pass only the visible range.

Notes for AI

• Use for scheduling and planning screens where people create and rearrange time blocks; pass events and persist in onCreate, onUpdate and onDelete.
• Event times are Date instants. The grid shows them in timeZone (or the browser's zone), so store UTC and let the calendar format them.
• Map your calendars to calendars with a color each; hidden calendars start toggled off in the calendar list.
• sampleEvents() and SAMPLE_CALENDARS in week-calendar-data.ts are demo content to remove.

Related

• Calendar: Browse dates in a clear, compact month view.
• Date picker: Choose a date without losing context.
• Time picker: Choose a time with sensible keyboard behavior.
• Popover: A small anchored surface for contextual information.
• Availability picker: 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://ui.xzero.co.uk/llms.txt