Only show these results:
private-preview

Using the Scheduling Component

This feature is a private preview release and should be used with caution. It may contain bugs, and its features and implementation will likely change before it is generally available.

The Scheduling Component is made from pre-built, composable, extensible web components that allow you to customize your Scheduling Page. In this tutorial, you'll learn how to do the following tasks:

  • Use components in your project.
  • Build a Scheduling Page with default components.
  • Style components with CSS shadow parts.
  • Extend the Scheduling Page with use case examples.

App versus Composable mode

The Scheduling Component supports two configuration modes: app and composable.

The default mode is app. It allows the nylas-scheduling component to render all sub-components by default. You can embed the pre-built components in your application with the minimum configuration.

The composable mode enables you to customize how each sub-component is arranged and rendered in the UI. You can use sub-components as standalone components.

Component list

The nylas-scheduling component can include the following sub-components:

  • nylas-booked-event-card
  • nylas-booking-form
  • nylas-cancel-booking-form
  • nylas-cancelled-event-card
  • nylas-date-picker
  • nylas-locale-switch
  • nylas-notification
  • nylas-open-hours-picker
  • nylas-selected-event-card
  • nylas-timeslot-picker

For more information on each component, such as supported properties, events, and CSS shadow parts, see the Scheduler UI Components reference documentation.

Scheduling flows

Scheduler follows the standard flow when no customization is made. You can add or skip the steps to create an optional flow. The following diagram illustrates the standard flow and the supported optional flows in Scheduler.

A flow diagram showing the Scheduler flow.

🚀 Pre-booking is coming soon!

Pre-booking

Pre-booking allows you to pause the booking flow to complete an action. When the booking type is set to pre-booking, Scheduler adds a placeholder event to the organizer's calendar before finalizing the booking. Scheduler will finalize the booking only when a specified action is completed, such as processing a payment.

Custom event handlers

Event handlers in Scheduler respond to user actions and dictate the operation that follows. Each event handler is associated with a specific type of event, such as timeslotSelected, timeslotConfirmed, dateSelected, and monthChanged.

The eventOverrides property allows you to customize the default event handlers so that you can implement specific logic or behavior for end user actions in Scheduler. For example, you can add or remove steps in your booking flow, track user interactions for analytics, update available time slots when the user selects a different date, and more.

For a use case example, see Customize event handlers.

Before you begin

Before you start using the Scheduling Component, you must complete the following tasks:

  1. Sign up for a Nylas account.

  2. Sign in to the v3 Dashboard and create a Nylas application.

  3. Generate an API key for your application and save it.

  4. Create a grant and save the grant ID.

  5. Download and install the Scheduler UI Components in your project.
    You can download the Scheduler UI Components package in either HTML/Vanilla JS or React.

    npm install @nylas/web-elements@latest   
    npm install @nylas/react@latest

    Alternately, you can use unpkg to directly include the web components in your HTML/Vanilla JS file:

    <script type="module" src="https://unpkg.com/@nylas/web-elements@latest"></script>

  6. Create a configuration object and a session token.

  7. Pass the session ID to the Scheduling Component.

Use components in your project

You can either include web components in your HTML/Vanilla JS file or import React components in your React application. The following examples show how to use the nylas-scheduling component:

<html>
  <head>
    <script type="module" src="https://unpkg.com/@nylas/web-elements@latest"></script>
  </head>
  <body>
    <nylas-scheduling></nylas-scheduling>
  </body>
</html>   
import React from 'react';
import { NylasScheduling } from '@nylas/react';

function App() {
  return <NylasScheduling />;
}

export default App;

Build a Scheduling Page with default components

To build a Scheduling Page with the default components, set the mode property to app and include the session ID. If nothing is configured in app mode, Scheduler follows the standard flow, as defined in the configuration object associated with the session ID.

To create a flow to reschedule an existing booking, include the rescheduleBookingId property and set it to the ID of the booking that you want to update.

To create a flow that cancels an existing booking, include the cancelBookingId property and set it to the ID of the booking that you want to cancel.

🔍 Nylas creates and returns a booking ID when you create a booking. For more information, see the /v3/scheduling/bookings endpoint documentation.

<NylasScheduling
  mode="app"
  sessionId={"<SESSION_ID>"}
/>   
<NylasScheduling
  mode="app"
  sessionId={"<SESSION_ID>"}
  rescheduleBookingId="<BOOKING_ID>"
/>   
<NylasScheduling
  mode="app"
  sessionId={"<SESSION_ID>"}
  cancelBookingId="<BOOKING_ID>"
/>

Style components using CSS shadow parts

The Scheduling Component supports CSS shadow parts (::part()) for a higher level of UI customization. CSS shadow parts allow you to style certain parts of a web component without having to modify the component's internal structure or styles directly. For more information on available shadow parts, see the Scheduler UI Components reference documentation.

The following CSS sets the component's background color to blue and the foreground color to white.

/* Your stylesheet */
nylas-scheduling::part(ndp__date--selected) {
  background-color: #2563EB;
  color: #FFFFFF;
}
nylas-scheduling component with CSS part

Use case examples

With the Scheduling Component, you can create a unique Scheduling Page that supports all of your business use cases. This section provides the following advanced use case examples:

Create one-off invites

You can use the date and time properties to create and display one-off invitations. These invitations have no date or time selected, and guests can book the event by entering their contact information.

The following example configures the default Scheduling Page state (defaultSchedulerState) to show the booking form with a pre-selected time. It also disables the Back button, so the end user can’t go back to the time slot selection page.

<NylasScheduling
  mode="app"
  sessionId={"<SESSION_ID>"}
  defaultSchedulerState={{
      showBookingForm: true,
      selectedTimeslot: {
        start_time: new Date('2024-02-22T22:12:53+0000'),
        end_time: new Date('2024-02-23T22:14:53+0000')
      }
  }}
/>

Configure the custom booking form

You can add the custom-booking-form slot between NylasScheduling element tags to add custom fields to the booking form, as in the example below.

<NylasScheduling
  mode="app"
  sessionId={"<SESSION_ID>"}
>
  <div slot="custom-booking-form">
    <input name="custom-field-1" />
    <input name="custom-field-2" />
  </div>
</NylasScheduling>

Skip the booking form

You can set the eventOverrides property to override the timeslotConfirmed event's default behavior, which proceeds to the booking form page.

The following example skips the booking form page and confirms the booking after the time confirmation step. After the booking is confirmed, the Scheduling Page displays a "thank you" message.

<NylasScheduling 
  sessionId="<SESSION_ID>" 
  mode="app"
  eventOverrides={{
    timeslotConfirmed: (event, connector) => {
      event.preventDefault()
      connector.scheduler.bookTimeslot({
        primaryParticipant: {
          name:"John Smith",
          email:"[email protected]"
        }
      }).then((response)=>{
        connector.schedulerStore.set('showThankYouMessage', true)
      })
    }
  }}
/>

Arrange components in composable mode

You can use the composable mode to customize how each sub-component is arranged and rendered in the UI.

The following example creates a date selection page with two panels: one to the left of the component, and one to the right. The panel to the left contains the date picker and locale switch sub-components, and the panel to the right displays the time slot picker.

<NylasScheduling mode="composable">
  <div class="select-date-page">
    <div class="left-panel">
      <nylas-date-picker></nylas-date-picker>
      <nylas-locale-switch></nylas-locale-switch>
    </div>
    <div class="right-panel">
        <nylas-timeslot-picker></nylas-timeslot-picker>
    </div>
  </div>
</NylasScheduling>

Customize event handlers

You can use the eventOverrides property to customize the default event handlers:

  • The Partial object allows you to override one, some, or all of the event handlers.
  • Custom event handlers return a Promise for asynchronous operations. This is useful when you want to fetch data, update UI components, or perform any tasks that require the outcome of other operations.
  • The NylasSchedulerConnectorInterface object allows custom event handlers to interact with the Nylas Scheduler API for more complex operations. The NylasSchedulerConnector exposes the following API interactions:
    • bookTimeslot
    • getAvailability
    • cancelBooking
    • rescheduleBooking

The following code overrides the default timeslotConfirmed handler.

<nylas-scheduling id="scheduler" eventOverrides='{"timeslotConfirmed": timeslotConfirmedHandler}'>
</nylas-scheduling>

document.addEventListener('DOMContentLoaded', function() {
  const schedulerElement = document.getElementById('scheduler');

  // Define the handler for timeslotConfirmed
  function timeslotConfirmedHandler(event, nylasConnector) {
    console.log("Timeslot confirmed event fired!");

    // Custom logic for booking the timeslot using the connector
    // Assuming 'bookTimeslot' is a method available in the connector
    nylasConnector.bookTimeslot(event.detail).then(bookingResponse => {
      console.log("Booking completed:", bookingResponse);
    }).catch(error => {
      console.error("Booking failed:", error);
    });

    // Sending data to analytics service
    sendToAnalyticsService(event.detail);
  }

  // Function to send data to analytics service
  function sendToAnalyticsService(data) {
    // Implement your analytics logic here. For example:
    console.log("Sending data to analytics service:", data);
    // Here you would typically make an API call or use a client-side analytics library
  }

  // Assign the handler to the scheduler's eventOverrides property
  schedulerElement.eventOverrides = { timeslotConfirmed: timeslotConfirmedHandler };
});