React Scheduler Component

:warning: Notice: This component uses mui/emotion/date-fns. if your project is not already using these libs, this component may not be suitable.

Installation

npm i @jackstenglein/react-scheduler

If you plan to use recurring events in your scheduler, install the rrule package. Pass either an RRule or an RRuleSet (for multiple rules, RDATEs, and EXDATEs) on event.recurring.

Usage

import { Scheduler } from "@jackstenglein/react-scheduler";

Example

<Scheduler
  view="month"
  events={[
    {
      event_id: 1,
      title: "Event 1",
      start: new Date("2021/5/2 09:30"),
      end: new Date("2021/5/2 10:30"),
    },
    {
      event_id: 2,
      title: "Event 2",
      start: new Date("2021/5/4 10:00"),
      end: new Date("2021/5/4 11:00"),
    },
  ]}
/>

Scheduler Props

All props are optional | Prop | Value | |----------|-------------| | height | number. Min height of table. Default: 600 | view | string. Initial view to load. options: "week", "month", "day". Default: "week" (if it's not null) | agenda | boolean. Activate agenda view | alwaysShowAgendaDays | boolean. if true, day rows without events will be shown | month | Object. Month view props. default: {weekDays: [0, 1, 2, 3, 4, 5], weekStartOn: 6, startHour: 9, endHour: 17,navigation: true,disableGoToDay: false} | week | Object. Week view props. default: { weekDays: [0, 1, 2, 3, 4, 5], weekStartOn: 6, startHour: 9, endHour: 17,step: 60,navigation: true,disableGoToDay: false} | day | Object. Day view props. default: {startHour: 9, endHour: 17, step: 60,navigation: true} | selectedDate | Date. Initial selected date. Default: new Date() | navigation | boolean. Show/Hide top bar date navigation. Default: true | stickyTop | number. CSS top offset (px) for sticky navigation and headers when the scheduler sits below a fixed app bar. Default: 0 | navigationPickerProps | CalendarPickerProps for top bar date navigation. Ref CalendarPicker API | disableViewNavigator | boolean. Show/Hide top bar date View navigator. Default: false | events | Array of ProcessedEvent. Default: [] type ProcessedEvent = {eventid: number or string;title: string;subtitle?: string;start: Date;end: Date;disabled?: boolean;recurring?: RRule | RRuleSet;color?: string or "palette.path";textColor?: string or "palette.path";editable?: boolean;deletable?: boolean;draggable?: boolean;allDay?: boolean;agendaAvatar?: React.ReactElement | stringsx?: Mui sx prop} | slots | Object. MUI-style slot components for replaceable UI regions. Keys: event, eventViewer, eventViewerTitle, eventViewerSubtitle, eventViewerExtra, eventViewerActionsExtra, loadingOverlay, cell, dayHeader, hourLabel, editor, resourceHeader, navigationExtra. Each value is a React component that receives the slot’s owner state as props. | slotProps | Object. Props (or (ownerState) => props callbacks) passed into each slot. Merged on top of the owner state. | editable | boolean. If true, the scheduler cell click will not open the editor, and the event item will not show the edit button, this is applied to all events, and can be overridden in each event property, see ProcessedEvent type. | deletable | boolean. Whether the event item will show the delete button, this is applied to all events, and can be overridden in each event property, see ProcessedEvent type. | draggable | boolean. Whether activate drag&drop for the events, this is applied to all events, and can be overridden in each event property, see ProcessedEvent type. | getRemoteEvents | Function(RemoteQuery). Return promise of array of events. Can be used as a callback to fetch events by parent component or fetch.type RemoteQuery = { start: Date; end: Date; view: "day" | "week" | "month";} | fields | Array of extra fields with configurations. Example: { name: "description", type: "input" , config: { label: "Description", required: true, min: 3, email: true, variant: "outlined", ....} | loading | boolean. Loading state of the calendar table | onConfirm | Function(event, action). Return promise with the new added/edited event use with remote data. action: add | edit | onDelete | Function(id) Return promise with the deleted event id to use with remote data. | disableViewer | boolean. If true, the viewer popover will be disabled globally | hideDates | boolean. Whether event items hide their start/end time. Default: false | resources | Array. Resources array to split event views with resources Example {assignee: 1,text: "User One", subtext: "Sales Manager", avatar: "https://picsum.photos/200/300", color: "#ab2d2d", } | resourceFields | Object. Map the resources correct fields. Example:{idField: "adminid", textField: "title", subTextField: "mobile",avatarField: "title", colorField: "background",} | resourceViewMode | Display resources mode. _Options*: default | vertical | tabs | onResourceChange | Function(resource: Resource): void. Triggered when the resource tabs changes, only applicable when resourceViewMode="tabs" | direction | string. Table direction. rtl | ltr | dialogMaxWidth | Edito dialog maxWith. Ex: lg | md | sm... Default:md | locale | Locale of date-fns. Default: enUS | hourFormat | Hour format. Options: 12 | 24. Default: 12 | timeZone| String, time zone IANA ID | translations | Object. Translations view props. default: { navigation: { month: "Month", week: "Week", day: "Day", today: "Today" agenda: "Agenda" }, form: { addTitle: "Add Event", editTitle: "Edit Event", confirm: "Confirm", delete: "Delete", cancel: "Cancel" }, event: { title: "Title", subtitle: "Subtitle", start: "Start", end: "End", allDay: "All Day"}, validation: { required: "Required", invalidEmail: "Invalid Email", onlyNumbers: "Only Numbers Allowed", min: "Minimum {{min}} letters", max: "Maximum {{max}} letters" }, moreEvents: "More...", noDataToDisplay: "No data to display", loading: "Loading..."} | onEventDrop | Function(event: DragEvent, droppedOn: Date, updatedEvent: ProcessedEvent, originalEvent: ProcessedEvent). Return a promise, used to update remote data of the dropped event. Return an event to update state internally, or void if event state is managed within component | onEventClick | Function(event: ProcessedEvent): void. Triggered when an event item is clicked | onEventEdit | Function(event: ProcessedEvent): void. Triggered when an event item is being edited from the popover | onCellClick | Function(start: Date, end: Date, resourceKey?: string, resourceVal?: string | number): void. Triggered when a cell in the grid is clicked | onSelectedDateChange | Function(date: Date): void. Triggered when the selectedDate prop changes by navigation date picker or today button | onViewChange | Function(view: View, agenda?: boolean): void. Triggered when navigation view changes | onClickMore | Function(date: Date, goToDay: Function(date: Date): void): void. Triggered when the "More..." button is clicked, it receives the date and a goToDay function that shows a day view for a specfic date.

SchedulerRef

Used to help manage and control the internal state of the Scheduler component from outside of Scheduler props, Example:

import { Scheduler } from "@jackstenglein/react-scheduler";
import type { SchedulerRef } from "@jackstenglein/react-scheduler/types"

const SomeComponent = () => {
  const calendarRef = useRef<SchedulerRef>(null);

  return <Fragment>
    <div>
      <Button onClick={()=>{
        calendarRef.current.scheduler.handleState("day", "view");
      }}>
        Change View
      </Button>
      <Button onClick={()=>{
        calendarRef.current.scheduler.triggerDialog(true, {
          start: /*Put the start date*/,
          end: /*Put the end date*/
        })
      }}>
        Add Event Tomorrow
      </Button>
    </div>

    <Scheduler
      ref={calendarRef}
      events={EVENTS}
      //...
    />
  </Fragment>
};

The calendarRef holds the entire internal state of the Scheduler component. Perhaps the most useful method inside the calendarRef is handleState, example:

calendarRef.current.scheduler.handleState(value, key);

consider looking inside SchedulerRef type to see all fields & methods available.

Demos

• Basic
• Remote Data
• Custom Fields
• Editor/Viewer Override
• Resources/View Mode
• Custom Cell Action
• Custom Event Slot

Todos

• [ ] Tests
• [x] Drag&Drop - partially
• [ ] Resizable
• [x] Recurring events - partially
• [x] Localization
• [x] Hour format 12 | 24