Calendar
ComplexScheduling
<co-calendar>Calendar is the full schedule with Day, Week and Month views, built from CalendarCell and AppointmentChip.
import { Calendar } from 'health-components';
Examples
Schedule
Day
Month
Color By Type
Usage
<Calendar defaultView="week" defaultDate="2026-10-09" colorBy
appointments={appts.map(a => ({ ...a, day: a.date.getDate(), slot: a.timeLabel }))}
onBook={(date, time) => openBooking(date, time)} onAppointmentClick={openAppointment} />
When to use
- The schedule screen and provider day views.
When not to use
- Picking one free time: TimeSlotPicker.
Variants and states
| Variant | What it is |
|---|---|
| day | Time rows with chips, blocked time, free slots. |
| week | 7 columns, today ringed. |
| month | 5 by 7 grid with counts and "+N more". |
| colorBy | Adds the Color by select. |
Accessibility
- Each view is a grid; every chip reads time, patient, type and status.
Do and don't
- Do: Keep filters (provider, location, status) above the calendar.
- Don't: Colour-only status.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
view | CalendarView | uncontrolled | 'day' | 'week' | 'month' (controlled) |
defaultView | CalendarView | 'week' | Initial view (uncontrolled) |
onViewChange | (view: CalendarView) => void | none | Called when the view switch changes |
date | string | uncontrolled | Shown date "YYYY-MM-DD" (controlled) |
defaultDate | string | `today` | Initial shown date "YYYY-MM-DD" (uncontrolled) |
onDateChange | (date: string) => void | none | Called with the new date on Previous, Today, Next and "+N more" |
today | string | `defaultDate`, else the device's date (read once) | Today's date "YYYY-MM-DD" (ringed, and where Today goes) |
appointments | CalendarAppointment[] | [] | Array<AppointmentChip props & {day: number, slot?: string}> |
title | string | the shown date ("Friday, October 9, 2026") | Heading text |
times | string[] | 8:00 AM to 12:00 PM | Day view rows |
blocks | Record<string, string> | {} | Record<time, reason>: blocked rows in the day view |
monthBlocks | Record<number, string> | {} | Record<day of month, reason>: blocked days in the month view |
colorBy | boolean | false | Shows the Color by select |
colorMode | CalendarColorMode | uncontrolled | Chip colouring: 'status' | 'type' (controlled) |
defaultColorMode | CalendarColorMode | 'status' | Initial chip colouring (uncontrolled) |
onColorModeChange | (mode: CalendarColorMode) => void | none | Called when the Color by select changes |
onNavigate | (direction: CalendarNavigation, date: string) => void | none | Called on Previous, Today and Next, after the date moves |
onBook | (date: string, time: string) => void | none | Called when the free slot of a day row is chosen |
onAppointmentClick | (appointment: CalendarAppointment) => void | none | Called when an appointment chip is chosen |
Also accepts native attributes, including defaultChecked, defaultValue, autoFocus, plus className and event handlers on the root element.
Angular, Vue and HTML
Register the elements once (Angular guide), then use <co-calendar>. Attributes take strings; arrays and objects are set as properties (Angular [prop], Vue :prop) or as JSON attributes. Callbacks are DOM events with the value in event.detail.
Angular template
<co-calendar view="…" default-view="…" [appointments]="appointments" (co-view-change)="onViewChange($event.detail)"></co-calendar>
| Kind | Name | Description |
|---|---|---|
| attribute | view | 'day' | 'week' | 'month' (controlled); default uncontrolled |
| attribute | default-view / defaultView | Initial view (uncontrolled); default 'week' |
| attribute | date | Shown date "YYYY-MM-DD" (controlled); default uncontrolled |
| attribute | default-date / defaultDate | Initial shown date "YYYY-MM-DD" (uncontrolled); default `today` |
| attribute | today | Today's date "YYYY-MM-DD" (ringed, and where Today goes); default `defaultDate`, else the device's date (read once) |
| property / JSON attribute | appointments | Array<AppointmentChip props & {day: number, slot?: string}>; default [] |
| attribute | title | Heading text; default the shown date ("Friday, October 9, 2026") |
| property / JSON attribute | times | Day view rows; default 8:00 AM to 12:00 PM |
| property / JSON attribute | blocks | Record<time, reason>: blocked rows in the day view; default {} |
| property / JSON attribute | month-blocks / monthBlocks | Record<day of month, reason>: blocked days in the month view; default {} |
| attribute | color-by / colorBy | Shows the Color by select; default false |
| attribute | color-mode / colorMode | Chip colouring: 'status' | 'type' (controlled); default uncontrolled |
| attribute | default-color-mode / defaultColorMode | Initial chip colouring (uncontrolled); default 'status' |
| attribute | default-checked / defaultChecked | |
| property / JSON attribute | default-value / defaultValue | |
| attribute | auto-focus / autoFocus | |
| event | co-view-change | Called when the view switch changes; default none (React: onViewChange) |
| event | co-date-change | Called with the new date on Previous, Today, Next and "+N more"; default none (React: onDateChange) |
| event | co-color-mode-change | Called when the Color by select changes; default none (React: onColorModeChange) |
| event | co-navigate | Called on Previous, Today and Next, after the date moves; default none (React: onNavigate) |
| event | co-book | Called when the free slot of a day row is chosen; default none (React: onBook) |
| event | co-appointment-click | Called when an appointment chip is chosen; default none (React: onAppointmentClick) |