weeklyschedule-reference

The Schedules web component enables administrators to create, manage, and visualize employee weekly work schedules across teams and locations.

Weekly schedule interface showing employee shifts, availability, and time-off requests

The Schedules component for web provides a calendar-based interface for managing your team schedules. Administrators can easily create shifts, assign employees, manage availability, and handle time-off requests all in one place.

The weekly view allows for drag-and-drop scheduling across multiple employees and locations, with visual indicators for conflicts, overstaffing, understaffing, and schedule gaps.

Read more about employee scheduling in our guides section

Basic Implementation

iframe

React

Feature Reference

Location Selector

Scheduling employees takes place on a per-location basis. When the current user has permissions to view multiple locations, use the location selector to switch between them.

Location selector

Pass the location parameter to control the currently active location.

Open Shifts

When open shifts are enabled (see Feature Flags), an open shifts row will appear on the schedules window.

Open shifts row

Open shifts allow managers to pre-define what shifts and the amount of labor needed on a specific week, then allow employees to provide their preferences for these shifts.

Publish Schedule

By default, when making changes to a weekly schedule, the changes applied as drafts and only visible to the managers. After done with changes, managers need to 'publish' the schedule for notifications to go out and for the changes to be reflected on employee calendars.

Turn off the publish_schedule feature flag if you'd like all changes to be immediate.

Publish schedules

Creating drafts, publishing, managing notifications are automatically handled by the WeeklySchedule component.

Time off requests

If the time_off feature flag is enabled, the user will be able to see and approve time off requests using the 'Time off requests' tab.

Time off requests

Read about time off management to learn more.

Event Types

The onEvent callback receives various events depending on user actions:

Event	Trigger	Payload
`onScheduleCreate`	A new shift or open shift is created	`current_week`, `shift` object
`onScheduleDelete`	A shift or open shift is deleted	`current_week`, `shift` object
`onScheduleEdit`	A shift is moved or edited	`current_week`, `location_ids`, old `shift` object, new `shift` object
`onScheduleWeekChange`	User switches week on the schedule view	`current_week`, `location_ids`, `new_week`
`onScheduleLocationChange`	User changes location selection	`current_week`, `location_ids`
`onScheduleBulkCopy`	Shifts are copied to future weeks	`current_week`, `location_ids`, `total_shifts`, `copy_method`, `paste_method`, `copy_to`
`onSchedulePublish`	Schedule is published	`current_week`, `location_ids`, `total_shifts`, `total_hours`, `labor_cost`, `notify`
`onSchedulePublishRevert`	A draft schedule is reverted	`current_week`, `location_ids`
`onSchedulePrint`	User prints the schedule	`current_week`, `location_ids`
`onTimeOffRequestsTabView`	Time off requests tab is opened	`current_week`, `location_ids`
`onScheduleViewMenuOpen`	View options menu is opened	`current_week`, `location_ids`
`onScheduleOpenShiftSubmit`	A staff member submits or claims an open shift	`current_week`, `location_ids`, `shift` object, `open_shift_preference`
`onScheduleOpenShiftRetract`	A staff member withdraws an open shift submission	`current_week`, `location_ids`, `shift` object, `open_shift_preference`
`onScheduleOpenShiftApprove`	An open shift submission is approved	`current_week`, `location_ids`, `shift` object, `employees`
`onTimeOffRequestCreate`	Staff or admin submits a time off request	`time_off_request` object
`onTimeOffRequestRetract`	Employee withdraws a pending request	`time_off_request` object
`onTimeOffRequestApprove`	Admin or manager approves a request	`time_off_request` object
`onTimeOffRequestDecline`	Admin or manager declines a request	`time_off_request` object

Parameters

Parameter	Type	Description
`start`	string	The starting date of the week to display in ISO format (YYYY-MM-DD). If not provided, the current week will be shown.
`location`	string	The external ID of the currently displayed location. Default to the first location provided in the `locations` array.

Next Steps

Read the our Shift Scheduling Guide for the most common use cases.

Weekly Schedules Reference

Basic Implementation#

Feature Reference#

Location Selector#

Open Shifts#

Publish Schedule#

Time off requests#

Event Types#

Parameters#

Next Steps#

Basic Implementation

Feature Reference

Location Selector

Open Shifts

Publish Schedule

Time off requests

Event Types

Parameters

Next Steps