@aldabil/react-scheduler

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 @aldabil/react-scheduler

If you plan to use recurring events in your scheduler, install rrule package

Usage

import { Scheduler } from "@aldabil/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, cellRenderer?:(props: CellProps) => JSX.Element, 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, cellRenderer?:(props: CellProps) => JSX.Element, navigation: true, disableGoToDay: false }
day	Object. Day view props. default: { startHour: 9, endHour: 17, step: 60, cellRenderer?:(props: CellProps) => JSX.Element, hourRenderer?:(hour: string) => JSX.Element, navigation: true }
selectedDate	Date. Initial selected date. Default: new Date()
navigation	boolean. Show/Hide top bar date navigation. Default: true
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 = { event*id: number or string; title: string; subtitle?: string; start: Date; end: Date; disabled?: boolean; recurring: RRule; color?: string or "palette.path"; textColor?: string or "palette.path"; editable?: boolean; deletable?: boolean; draggable?: boolean; allDay?: boolean; agendaAvatar?: React.ReactElement | string sx?: Mui sx prop }
eventRenderer	Function(event:ProcessedEvent): JSX.Element. A function that overrides the event item render function, see demo _Custom Event Renderer* below
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
loadingComponent	Custom component to override the default CircularProgress
onConfirm	Function(event, action). Return promise with the new added/edited event use with remote data. action: add
onDelete	Function(id) Return promise with the deleted event id to use with remote data.
customEditor	Function(scheduler). Override editor modal. Provided prop scheduler object with helper props: { state: state obj, close(): void loading(status: boolean): void edited?: ProcessedEvent onConfirm(event: ProcessedEvent, action:EventActions): void }
customViewer	Function(event: ProcessedEvent, close: () => void). Used to render fully customized content of the event popper. If used, viewerExtraComponent & viewerTitleComponent will be ignored
viewerExtraComponent	Function(fields, event) OR Component. Additional component in event viewer popper
viewerTitleComponent	Function(event). Helper function to render custom title in event popper
viewerSubtitleComponent	Function(event). Helper function to render custom subtitle in event popper
disableViewer	boolean. If true, the viewer popover will be disabled globally
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: "admin*id", textField: "title", subTextField: "mobile", avatarField: "title", colorField: "background", }
resourceHeaderComponent	Function(resource). Override header component of resource
resourceViewMode	Display resources mode. _Options*: default
onResourceChange	Function(resource: Resource): void. Triggered when the resource tabs changes, only applicable when resourceViewMode="tabs"
direction	string. Table direction. rtl
dialogMaxWidth	Edito dialog maxWith. Ex: lg
locale	Locale of date-fns. Default: enUS
hourFormat	Hour format. Options: 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
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
stickyNavigation	If true, the navigation controller bar will be sticky
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 "@aldabil/react-scheduler";
import type { SchedulerRef } from "@aldabil/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 Renderer

Todos

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