Skip to main content

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​

Storybook

Day​

Storybook

Month​

Storybook

Color By Type​

Storybook

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​

VariantWhat it is
dayTime rows with chips, blocked time, free slots.
week7 columns, today ringed.
month5 by 7 grid with counts and "+N more".
colorByAdds 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​

PropTypeDefaultDescription
viewCalendarViewuncontrolled'day' | 'week' | 'month' (controlled)
defaultViewCalendarView'week'Initial view (uncontrolled)
onViewChange(view: CalendarView) => voidnoneCalled when the view switch changes
datestringuncontrolledShown date "YYYY-MM-DD" (controlled)
defaultDatestring`today`Initial shown date "YYYY-MM-DD" (uncontrolled)
onDateChange(date: string) => voidnoneCalled with the new date on Previous, Today, Next and "+N more"
todaystring`defaultDate`, else the device's date (read once)Today's date "YYYY-MM-DD" (ringed, and where Today goes)
appointmentsCalendarAppointment[][]Array<AppointmentChip props & {day: number, slot?: string}>
titlestringthe shown date ("Friday, October 9, 2026")Heading text
timesstring[]8:00 AM to 12:00 PMDay view rows
blocksRecord<string, string>{}Record<time, reason>: blocked rows in the day view
monthBlocksRecord<number, string>{}Record<day of month, reason>: blocked days in the month view
colorBybooleanfalseShows the Color by select
colorModeCalendarColorModeuncontrolledChip colouring: 'status' | 'type' (controlled)
defaultColorModeCalendarColorMode'status'Initial chip colouring (uncontrolled)
onColorModeChange(mode: CalendarColorMode) => voidnoneCalled when the Color by select changes
onNavigate(direction: CalendarNavigation, date: string) => voidnoneCalled on Previous, Today and Next, after the date moves
onBook(date: string, time: string) => voidnoneCalled when the free slot of a day row is chosen
onAppointmentClick(appointment: CalendarAppointment) => voidnoneCalled 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>
KindNameDescription
attributeview'day' | 'week' | 'month' (controlled); default uncontrolled
attributedefault-view / defaultViewInitial view (uncontrolled); default 'week'
attributedateShown date "YYYY-MM-DD" (controlled); default uncontrolled
attributedefault-date / defaultDateInitial shown date "YYYY-MM-DD" (uncontrolled); default `today`
attributetodayToday's date "YYYY-MM-DD" (ringed, and where Today goes); default `defaultDate`, else the device's date (read once)
property / JSON attributeappointmentsArray<AppointmentChip props & {day: number, slot?: string}>; default []
attributetitleHeading text; default the shown date ("Friday, October 9, 2026")
property / JSON attributetimesDay view rows; default 8:00 AM to 12:00 PM
property / JSON attributeblocksRecord<time, reason>: blocked rows in the day view; default {}
property / JSON attributemonth-blocks / monthBlocksRecord<day of month, reason>: blocked days in the month view; default {}
attributecolor-by / colorByShows the Color by select; default false
attributecolor-mode / colorModeChip colouring: 'status' | 'type' (controlled); default uncontrolled
attributedefault-color-mode / defaultColorModeInitial chip colouring (uncontrolled); default 'status'
attributedefault-checked / defaultChecked
property / JSON attributedefault-value / defaultValue
attributeauto-focus / autoFocus
eventco-view-changeCalled when the view switch changes; default none (React: onViewChange)
eventco-date-changeCalled with the new date on Previous, Today, Next and "+N more"; default none (React: onDateChange)
eventco-color-mode-changeCalled when the Color by select changes; default none (React: onColorModeChange)
eventco-navigateCalled on Previous, Today and Next, after the date moves; default none (React: onNavigate)
eventco-bookCalled when the free slot of a day row is chosen; default none (React: onBook)
eventco-appointment-clickCalled when an appointment chip is chosen; default none (React: onAppointmentClick)