Date & Time

Scheduler

Month-view event calendar that lays events onto day cells.

Import

tsx

import { Scheduler } from "@cooud-ui/ui";

bash

npx cooud-ui add scheduler

Examples

Month view

A month-grid calendar that lays events onto day cells. Drive the visible month with `month`/`onMonthChange`, pass token-coloured `events`, and opt into a `today` highlight. Days overflowing three events collapse into a `+N more` row.

June 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
31	1	2	3	4	5	6
7	8	9	10	11	12	13
14	15	16	17	18	19	20
21	22	23	24	25	26	27
28	29	30	1	2	3	4

tsx

const events: SchedulerEvent[] = [
  { id: "standup", title: "Team standup", date: new Date(2026, 5, 2), color: "primary" },
  { id: "design", title: "Design review", date: new Date(2026, 5, 9), color: "info" },
  { id: "ship", title: "v2 ship", date: new Date(2026, 5, 12), color: "success" },
  { id: "retro", title: "Sprint retro", date: new Date(2026, 5, 12), color: "warning" },
  { id: "launch", title: "Launch party", date: new Date(2026, 5, 24), color: "success" },
];

// Fixed month keeps SSR + client identical (avoids hydration drift).
const [month, setMonth] = useState<Date>(() => new Date(2026, 5, 1));

return (
  <Scheduler
    month={month}
    onMonthChange={setMonth}
    events={events}
    today={new Date(2026, 5, 1)}
    className="max-w-2xl"
  />
);

API Reference

Generated from the component's exported types.

SchedulerProps

Extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue">

Prop	Type	Default	Description
`month`	`Date`	—	Controlled visible month. Provide together with `onMonthChange`.
`defaultMonth`	`Date`	—	Initial visible month for the uncontrolled case. Defaults to "today".
`onMonthChange`	`(month: Date) => void`	—	Called with the first day of the next visible month on Prev/Today/Next.
`events`	`SchedulerEvent[]`	`[]`	Events to lay out across the grid. Bucketed by calendar day.
`onEventClick`	`(event: SchedulerEvent) => void`	—	Fired when an event chip is activated.
`onDayClick`	`(date: Date) => void`	—	Fired when a day cell (not a chip) is activated, with that day's date.
`today`	`Date`	—	The day to highlight as "today". Optional and defaulting to `undefined` so server render and first client paint are deterministic — pass a stable Date (or compute one in an effect) to light up the current day without a hydration mismatch.
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`	`0`	Locale-aware start of the week (0 = Sunday … 6 = Saturday). Defaults to `0`, matching the Sun…Sat header.
`ariaLabel`	`string`	`"Event calendar"`	Accessible label for the grid. Defaults to "Event calendar".