Quick reference

CLI commands

Bash

# Add UI components (month/week/day/agenda views, event dialogs)
npx @fivfold/ui add calendar

# Add backend scaffolding (Express/NestJS + TypeORM)
npx @fivfold/api add calendar --framework=nestjs --orm=typeorm

# Use MongoDB + Mongoose
npx @fivfold/api add calendar --framework=nestjs --orm=mongoose --database=mongodb

# Use Express + Prisma
npx @fivfold/api add calendar --framework=express --orm=prisma

# Dry run to preview files
npx @fivfold/ui add calendar --dry-run
npx @fivfold/api add calendar --dry-run

Overview

The Calendar Kit provides a complete calendar UI with four views — Month, Week, Day, and Agenda — plus event creation/editing dialogs with color categories, all-day toggles, attendee management, location, and recurrence fields. Built with shadcn/ui primitives and date-fns. Fully responsive: mobile defaults to Agenda view, tablet to Week, desktop to Month. Supported stack combinations:

Layer	Options
Framework	NestJS, Express
SQL	TypeORM (PostgreSQL, MySQL, MariaDB, MSSQL), Prisma
NoSQL	Mongoose (MongoDB), Prisma (MongoDB connector)
Cloud NoSQL	Azure Cosmos DB SDK, AWS DynamoDB SDK

Demo

This demo is presented with Mock Data

April 2026

Sun

Mon

Tue

Wed

Thu

Fri

Sat

Guide

Step-by-step guides for the frontend UI and backend API integration. Pick Frontend first in the sidebar, then the rest of your stack, for aligned dev-server and API docs.

The Calendar Kit is built exclusively with shadcn/ui primitives and date-fns. Follow the steps below to install, integrate, and customize the UI.

1Install the Calendar Kit

Run the FivFold UI CLI to add the Calendar Kit to your project. Ensure you have run npx @fivfold/ui init first.

Bash

npx @fivfold/ui add calendar

The Kit is copied to @/components/ui/kits/calendar/ (or your configured kits alias in fivfold.json). shadcn/ui primitives and date-fns are installed automatically.

2Generated file structure

The command creates a self-contained folder with separate files for each view and dialog:

File tree

kits/calendar/
  types.ts                  # Shared types (FivFoldCalendarEvent, CalendarKitProps, etc.)
  calendar-header.tsx       # Navigation arrows, Today button, view switcher
  month-view.tsx            # 7-column month grid with event pills and overflow count
  week-view.tsx             # 7-column × 24-row time grid with all-day row
  day-view.tsx              # Single-day hourly time slots with event blocks
  agenda-view.tsx           # Chronological scrollable event list grouped by date
  event-card.tsx            # Reusable event pill/card component with color theming
  event-detail-dialog.tsx   # Sheet (mobile) / Dialog (desktop) showing full event details
  create-event-dialog.tsx   # Create + Edit form with date pickers, color, location, recurrence
  index.tsx                 # Main CalendarKit component and re-exports

3Import and use in your app

Import the main component and types from the kit folder:

app/calendar/page.tsx

import { CalendarKit } from "@/components/ui/kits/calendar";
import type { FivFoldCalendarEvent } from "@/components/ui/kits/calendar";

const INITIAL_EVENTS: FivFoldCalendarEvent[] = [
  {
    id: "1",
    title: "Team Standup",
    startDate: "2025-04-16T09:30:00.000Z",
    endDate: "2025-04-16T10:00:00.000Z",
    isAllDay: false,
    color: "blue",
    location: "Zoom",
    createdAt: new Date().toISOString(),
    updatedAt: new Date().toISOString(),
  },
];

export function CalendarPage() {
  const [events, setEvents] = React.useState(INITIAL_EVENTS);

  return (
    <div className="h-[700px]">
      <CalendarKit
        events={events}
        onEventsChange={setEvents}
        defaultView="month"
        showTodayButton
        showViewSwitcher
        showAttendees
        showLocation
      />
    </div>
  );
}

4Props reference

The Calendar Kit exposes a single CalendarKit component. All props are optional except events.

Data & State

Core event data and change callbacks.

Prop	Type	Purpose
events	FivFoldCalendarEvent[]	List of events to display across all views.
onEventsChange	(events) => void	Fired when events are created, updated, or deleted internally.
defaultView	"month" \| "week" \| "day" \| "agenda"	Initial calendar view. Defaults to "month".
defaultDate	string (ISO)	Initial date to navigate to. Defaults to today.
weekStartsOn	0 \| 1	0 = Sunday (default), 1 = Monday. Affects month and week views.

Visibility & Layout

Prop	Type	Purpose
showTodayButton	boolean	Show "Today" navigation button. Default true.
showViewSwitcher	boolean	Show Month/Week/Day/Agenda tabs. Default true.
showAttendees	boolean	Show attendee avatars and count in event detail. Default true.
showLocation	boolean	Show location in event cards and detail dialog. Default true.
forceLayout	"mobile" \| "tablet" \| "desktop"	Override responsive breakpoints. Dialogs use Sheet on mobile, Dialog on desktop.
attendeeSuggestions	FivFoldCalendarAttendee[]	List of users to show in the attendee autocomplete search when creating/editing events. Populate from your users database. Each entry requires id, name, email, initials (and optionally avatar, status).

Callbacks

Prop	Type	Purpose
onEventClick	(event) => void	Override default event detail dialog. Use for custom routing or panel.
onCreateEvent	(partial) => void	Override default create dialog. Receives partial event with date fields pre-filled.
onDeleteEvent	(eventId) => void	Override default delete. Use to call DELETE /api/calendar/events/:id.

Reminders (notification stubs)

The create-event dialog lets users add reminders (e.g. 15 minutes before, 1 hour before). The UI stores reminders on the event object and sends them to the API. The backend includes stub endpoints at POST /calendar/events/:id/reminders and DELETE /calendar/events/:id/reminders/:rid that you must wire up to your own notification service. Supported options include:

Firebase Cloud Messaging (FCM) — push notifications for web/mobile
AWS SNS — SMS, email, or push
OneSignal — cross-platform push
Twilio — SMS delivery
Resend / Postmark — transactional email reminders

The stub methods addReminder and removeReminder are also declared on the service port interface (I{moduleName}Service) for you to implement.

Attendee suggestions

Pass your user list via attendeeSuggestions to enable the autocomplete search in the create/edit dialog. Users can also type a raw email address to add an attendee not in the list. Fetch your users from your auth provider or database and map them toFivFoldCalendarAttendee:

TSX

import { CalendarKit } from "@/components/ui/kits/calendar"
import type { FivFoldCalendarAttendee } from "@/components/ui/kits/calendar/types"

// Map from your own User model
const suggestions: FivFoldCalendarAttendee[] = users.map((u) => ({
  id: u.id,
  name: u.displayName,
  email: u.email,
  initials: u.displayName.slice(0, 2).toUpperCase(),
  avatar: u.avatarUrl,
}))

<CalendarKit
  events={events}
  attendeeSuggestions={suggestions}
/>

Event Color Categories

Set color on each FivFoldCalendarEvent to theme its pill and dot:

Value	Appearance
"default"	Primary color (follows your shadcn theme)
"red"	Red tinted pill
"orange"	Orange tinted pill
"yellow"	Yellow tinted pill
"green"	Green tinted pill
"teal"	Teal tinted pill
"blue"	Blue tinted pill
"purple"	Purple tinted pill
"pink"	Pink tinted pill

5Integration with backend

You own the wiring

The step-by-step guides, environment variables, and dev-server proxy or rewrite examples are suggestions—not a mandated layout. You should read the generated files, your existing routes and auth, and your deployment topology, then choose URLs, origins, and headers that match your app. We encourage verifying every connection yourself before shipping.

Step-by-step: Calendar UI → API

Examples match the Frontend choice in the stack sidebar (Next.js). Your mount paths may differ; adjust prefixes to match how you register routes and proxies.

Chat kit: follow the ordered full-stack checklist for dev user middleware, /socket.io proxying, headers, and the integration host.

Next.js → API

Prefer rewrites in next.config.ts so browser code can use same-origin paths like /api/calendar/... while the dev server forwards to your backend. Alternatively set NEXT_PUBLIC_API_URL and call that base from client code.

next.config.ts

// next.config.ts — example rewrite to API on another port
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: 'http://localhost:3001/:path*', // your Nest/Express port
      },
    ];
  },
};

export default nextConfig;

If the app and API both use port 3000, run the API on a different port (e.g. 3001) or use a monorepo BFF pattern.

API → browser (CORS)

Allow your UI's dev origin on the API. For Next.js that is typically http://localhost:3000 (plus 127.0.0.1 if you use it).

Production

Use your real API base (e.g. https://api.example.com/calendar) and lock CORS to known web origins — not *.

Connecting Calendar (UI layer) data to your user system

Event and attendee props are user-agnostic in the kit. Your data hooks must load events for the signed-in user and send the same user context to the API when creating or updating events.

Include auth headers on every mutating call (create event, delete event) so the backend can enforce ownership.
Map attendee display names and avatars from your user directory if the API returns ids only.
Use onCreateEvent and onDeleteEvent callbacks to wire the kit to your API instead of its built-in local state.

Inspect generated code

Open the scaffolded entities, schemas, or Prisma models for this kit and compare field names (userId, ownerId, etc.) to your User table or IdP subject. Migrate or add FKs where needed—FivFold cannot know your prior schema.

6shadcn/ui primitives

Adding the Calendar Kit installs these shadcn/ui primitives if not already present:

Component	Used in
button	Header navigation, create event, detail actions
dialog	Event detail and create form on desktop
sheet	Event detail and create form on mobile (bottom sheet)
tabs	View switcher (Month / Week / Day / Agenda) on desktop
dropdown-menu	View switcher on mobile
scroll-area	Agenda view list, week/day time grid
badge	All-day indicator, attendee status
avatar	Attendee avatars in event detail
input	Event title, location, date/time fields
label	Form field labels in create dialog
textarea	Event description field
select	Color picker, recurrence selector
switch	All-day toggle in create dialog
separator	Visual dividers in dialogs and agenda view
tooltip	Hover hints on header buttons

7Additional dependencies

The kit uses date-fns for all date arithmetic and formatting, and lucide-react for icons. Both are added automatically when you run npx @fivfold/ui add calendar.

Package	Purpose
date-fns	Date arithmetic, formatting, week/month calculations
lucide-react	Icons (ChevronLeft, ChevronRight, MapPin, Users, etc.)