# Calendar

Page: /docs/components/calendar

{/* Figma: Meridian → Calendar (docs 45:1243, component set 23:28135). Spec: docs/design-system/meridian/calendar.md */}

Deadlines on the days they fall, in a month grid or an agenda of the days ahead. Each filing is a chip that leads with its jurisdiction flag. Calendar is a product element: on the website it appears in product shots and animations of the compliance calendar, never as a live control.

```tsx
"use client";

import { Calendar, type CalendarEvent } from "@commenda/meridian/ui/calendar";
import { GBFlag, SGFlag, USFlag } from "@commenda/pathfinder/flags";
import { useState } from "react";

const ENTITIES = {
	us: { id: "us", label: "Commenda Technologies Inc.", flag: <USFlag size={12} /> },
	uk: { id: "uk", label: "Commenda UK Ltd", flag: <GBFlag size={12} /> },
	sg: { id: "sg", label: "Commenda Singapore Pte. Ltd.", flag: <SGFlag size={12} /> },
};

const CAT = {
	payroll: { id: "payroll", label: "Payroll & Employment", tone: "amber" as const },
	entity: { id: "entity", label: "Entity Compliance", tone: "blue" as const },
	direct: { id: "direct", label: "Direct Tax", tone: "indigo" as const },
	tp: { id: "tp", label: "Transfer Pricing", tone: "purple" as const },
	indirect: { id: "indirect", label: "Indirect Tax", tone: "teal" as const },
};

const ev = (
	id: string,
	date: string,
	title: string,
	entity: keyof typeof ENTITIES,
	category: keyof typeof CAT,
	status?: CalendarEvent["status"],
	assignee?: string,
): CalendarEvent => ({
	id,
	date,
	title,
	entity: ENTITIES[entity],
	category: CAT[category],
	status,
	assignee: assignee ? { kind: "person", name: assignee } : undefined,
});

const EVENTS: CalendarEvent[] = [
	ev("1", "2026-09-30", "GST F5 Q2", "sg", "indirect", { label: "Filed", appearance: "filed" }),
	ev("2", "2026-10-01", "Delaware franchise tax", "us", "entity", {
		label: "Filed",
		appearance: "filed",
	}),
	ev("3", "2026-10-05", "Form 941 deposit", "us", "payroll", {
		label: "Filed",
		appearance: "filed",
	}),
	ev("4", "2026-10-07", "VAT return Q3", "uk", "indirect", {
		label: "Overdue",
		tone: "error",
		appearance: "overdue",
	}),
	ev("5", "2026-10-09", "Customs declaration", "uk", "indirect", {
		label: "Filed",
		appearance: "filed",
	}),
	ev(
		"6",
		"2026-10-13",
		"PAYE RTI October",
		"uk",
		"payroll",
		{ label: "In progress", tone: "info" },
		"Sara Shah",
	),
	ev(
		"7",
		"2026-10-13",
		"Delaware annual report",
		"us",
		"entity",
		{ label: "Not started" },
		"Arjun Singh",
	),
	ev("8", "2026-10-14", "Master file", "sg", "tp", { label: "Not started" }, "Tom Sato"),
	ev(
		"9",
		"2026-10-15",
		"Form 1120",
		"us",
		"direct",
		{ label: "Extended", appearance: "extended" },
		"Sara Shah",
	),
	ev(
		"10",
		"2026-10-15",
		"CA franchise tax",
		"us",
		"direct",
		{ label: "Due soon", tone: "warning" },
		"Arjun Singh",
	),
	ev(
		"11",
		"2026-10-15",
		"Form 5472",
		"us",
		"tp",
		{ label: "Due soon", tone: "warning" },
		"Tom Sato",
	),
	ev("12", "2026-10-15", "NY CT-3", "us", "direct", { label: "Not started" }),
	ev("13", "2026-10-19", "ECI filing", "sg", "direct", { label: "Not started" }, "Tom Sato"),
	ev("14", "2026-10-20", "Form 941 Q3", "us", "payroll"),
	ev("15", "2026-10-22", "Import duty return", "uk", "indirect"),
	ev("16", "2026-10-28", "GST F5 Q3", "sg", "indirect"),
	ev("17", "2026-10-30", "Confirmation statement", "uk", "entity"),
	ev("18", "2026-10-31", "CT600", "uk", "direct"),
];

export function CalendarViews() {
	const [view, setView] = useState<"month" | "agenda" | "auto">("month");
	return (
		<div className="not-prose my-4">
			<Calendar
				label="Compliance calendar"
				events={EVENTS}
				dateConfig={{ today: "2026-10-13", locale: "en-US", weekStartsOn: 0 }}
				monthConfig={{ defaultValue: "2026-10" }}
				viewConfig={{ value: view, onValueChange: setView }}
				entityFilterConfig={{ entities: Object.values(ENTITIES), defaultValue: [] }}
			/>
		</div>
	);
}
```

## Usage [#usage]

```tsx
import { Calendar } from "@commenda/meridian/ui/calendar";

<Calendar
  label="Compliance calendar"
  events={filings}
  dateConfig={{ today: "2026-10-13", weekStartsOn: 0 }}
  monthConfig={{ defaultValue: "2026-10" }}
/>;
```

## Views [#views]

Month shows the weeks of the month, Sunday first, with up to three filings a day and "N more". Agenda lists the days ahead with the full row: status, assignee and actions. Narrow shots default to Agenda. Switch views in the toolbar below.

```tsx
"use client";

import { Calendar, type CalendarEvent } from "@commenda/meridian/ui/calendar";
import { GBFlag, SGFlag, USFlag } from "@commenda/pathfinder/flags";
import { useState } from "react";

const ENTITIES = {
	us: { id: "us", label: "Commenda Technologies Inc.", flag: <USFlag size={12} /> },
	uk: { id: "uk", label: "Commenda UK Ltd", flag: <GBFlag size={12} /> },
	sg: { id: "sg", label: "Commenda Singapore Pte. Ltd.", flag: <SGFlag size={12} /> },
};

const CAT = {
	payroll: { id: "payroll", label: "Payroll & Employment", tone: "amber" as const },
	entity: { id: "entity", label: "Entity Compliance", tone: "blue" as const },
	direct: { id: "direct", label: "Direct Tax", tone: "indigo" as const },
	tp: { id: "tp", label: "Transfer Pricing", tone: "purple" as const },
	indirect: { id: "indirect", label: "Indirect Tax", tone: "teal" as const },
};

const ev = (
	id: string,
	date: string,
	title: string,
	entity: keyof typeof ENTITIES,
	category: keyof typeof CAT,
	status?: CalendarEvent["status"],
	assignee?: string,
): CalendarEvent => ({
	id,
	date,
	title,
	entity: ENTITIES[entity],
	category: CAT[category],
	status,
	assignee: assignee ? { kind: "person", name: assignee } : undefined,
});

const EVENTS: CalendarEvent[] = [
	ev("1", "2026-09-30", "GST F5 Q2", "sg", "indirect", { label: "Filed", appearance: "filed" }),
	ev("2", "2026-10-01", "Delaware franchise tax", "us", "entity", {
		label: "Filed",
		appearance: "filed",
	}),
	ev("3", "2026-10-05", "Form 941 deposit", "us", "payroll", {
		label: "Filed",
		appearance: "filed",
	}),
	ev("4", "2026-10-07", "VAT return Q3", "uk", "indirect", {
		label: "Overdue",
		tone: "error",
		appearance: "overdue",
	}),
	ev("5", "2026-10-09", "Customs declaration", "uk", "indirect", {
		label: "Filed",
		appearance: "filed",
	}),
	ev(
		"6",
		"2026-10-13",
		"PAYE RTI October",
		"uk",
		"payroll",
		{ label: "In progress", tone: "info" },
		"Sara Shah",
	),
	ev(
		"7",
		"2026-10-13",
		"Delaware annual report",
		"us",
		"entity",
		{ label: "Not started" },
		"Arjun Singh",
	),
	ev("8", "2026-10-14", "Master file", "sg", "tp", { label: "Not started" }, "Tom Sato"),
	ev(
		"9",
		"2026-10-15",
		"Form 1120",
		"us",
		"direct",
		{ label: "Extended", appearance: "extended" },
		"Sara Shah",
	),
	ev(
		"10",
		"2026-10-15",
		"CA franchise tax",
		"us",
		"direct",
		{ label: "Due soon", tone: "warning" },
		"Arjun Singh",
	),
	ev(
		"11",
		"2026-10-15",
		"Form 5472",
		"us",
		"tp",
		{ label: "Due soon", tone: "warning" },
		"Tom Sato",
	),
	ev("12", "2026-10-15", "NY CT-3", "us", "direct", { label: "Not started" }),
	ev("13", "2026-10-19", "ECI filing", "sg", "direct", { label: "Not started" }, "Tom Sato"),
	ev("14", "2026-10-20", "Form 941 Q3", "us", "payroll"),
	ev("15", "2026-10-22", "Import duty return", "uk", "indirect"),
	ev("16", "2026-10-28", "GST F5 Q3", "sg", "indirect"),
	ev("17", "2026-10-30", "Confirmation statement", "uk", "entity"),
	ev("18", "2026-10-31", "CT600", "uk", "direct"),
];

export function CalendarViews() {
	const [view, setView] = useState<"month" | "agenda" | "auto">("month");
	return (
		<div className="not-prose my-4">
			<Calendar
				label="Compliance calendar"
				events={EVENTS}
				dateConfig={{ today: "2026-10-13", locale: "en-US", weekStartsOn: 0 }}
				monthConfig={{ defaultValue: "2026-10" }}
				viewConfig={{ value: view, onValueChange: setView }}
				entityFilterConfig={{ entities: Object.values(ENTITIES), defaultValue: [] }}
			/>
		</div>
	);
}
```

## Chips [#chips]

A 3 bar in the category tone, the flag, then the title. Status shows on the chip itself: overdue is red in every category, filed ends in a green completed icon, extended is dashed.

```tsx
{
  title: "VAT return Q3",
  date: "2026-10-07",
  entity: { id: "uk", label: "Commenda UK Ltd", flag: <GBFlag size={12} /> },
  category: { id: "indirect", label: "Indirect Tax", tone: "teal" },
  status: { label: "Overdue", tone: "error", appearance: "overdue" },
}
```

## Colors [#colors]

The color of a chip is its filing category, not its status, and it lives in the 3px bar. Each category has a tone: `amber`, `blue`, `indigo`, `purple`, `teal`, `rose` or `neutral`. Status only changes the shape.

## Behavior [#behavior]

What happens in the product, so animations and shots tell the truth.

| Interaction | What happens |
| --- | --- |
| Click a chip | Opens the filing’s Popover next to it. |
| Click "N more" | Opens a Popover listing every filing that day. |
| Hover a chip | Fills soft-pearl 200; the title stays. |
| Change view | Month and Agenda share the toolbar; the selected day stays. |

## Anatomy [#anatomy]

One chip: 3 bar in the category tone, 4 gap, flag 12, 4 gap, title Label/12 Strong in soft-pearl 1000, radius 4, 20 high. Filed adds a 12 completed icon at the end; overdue adds the red failed mark. A day in the month grid is 168 × 120 with 4 padding.

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` |  |
| `events` (required) | `readonly CalendarEvent[]` |  |
| `dateConfig` (required) | `{ today: string; locale?: string; weekStartsOn?: 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6; }` |  |
| `monthConfig` | `SelectionProps<string>` |  |
| `viewConfig` | `SelectionProps<CalendarView>` |  |
| `entityFilterConfig` | `SelectionProps<readonly string[]> & { entities: readonly CalendarEntity[]; label?: string; }` |  |
| `eventConfig` | `{ renderPreview?: (event: CalendarEvent) => ReactNode; onOpen?: (event: CalendarEvent) => void; getMenu?: (event: CalendarEvent) => DropdownMenu; }` |  |
| `addConfig` | `{ actions: readonly CalendarAddAction[]; }` |  |
| `stateConfig` | `{ isLoading?: boolean; loadingLabel?: string; error?: { message: string; onRetry?: () => void; }; emptyContent?: ReactNode; }` |  |
| `onVisibleRangeChange` | `(range: CalendarVisibleRange) => void` |  |
| `className` | `string` |  |

**`dateConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `today` (required) | `string` |  |
| `locale` | `string` |  |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` |  |

**`monthConfig` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `value` (required) | `string` |  |
| `onValueChange` (required) | `(value: string) => void` |  |

Do not supply: `defaultValue`.

**`monthConfig` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `defaultValue` | `string` |  |
| `onValueChange` | `(value: string) => void` |  |

Do not supply: `value`.

**`viewConfig` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `value` (required) | `"auto" \| "month" \| "agenda"` |  |
| `onValueChange` (required) | `(value: CalendarView) => void` |  |

Do not supply: `defaultValue`.

**`viewConfig` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `defaultValue` | `"auto" \| "month" \| "agenda"` |  |
| `onValueChange` | `(value: CalendarView) => void` |  |

Do not supply: `value`.

**`eventConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `renderPreview` | `(event: CalendarEvent) => ReactNode` |  |
| `onOpen` | `(event: CalendarEvent) => void` |  |
| `getMenu` | `(event: CalendarEvent) => DropdownMenu` |  |

**`addConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `actions` (required) | `readonly CalendarAddAction[]` |  |

**`stateConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `isLoading` | `boolean` |  |
| `loadingLabel` | `string` |  |
| `error` | `{ message: string; onRetry?: () => void; }` |  |
| `emptyContent` | `ReactNode` |  |

**`stateConfig.error` fields**

| Field | Type | Description |
| --- | --- | --- |
| `message` (required) | `string` |  |
| `onRetry` | `() => void` |  |

## Best practices [#best-practices]

- Keep titles to the form or return name: "Form 1120", "GST F5 Q3".
- Use Agenda below about 900 wide: month chips truncate to a few letters in a narrow shot.
- Never color by status beyond overdue: the tone is the category.
- Lead every filing with its flag, even when the shot shows one company.
- Use real-looking demo data from the approved names and countries list.
- Source: Pathfinder Calendar. Meridian keeps it as is; the prototype is not carried over.
