Version:
Only show these results:

Using the Scheduling Component

You can use the Scheduling Component to create a unique Scheduling Page where your users can book events.

How the Scheduling Component works

Nylas offers the Scheduling Component as a pre-built, extensible web- (HTML/Vanilla JS) and React-based UI Component. After you add it to your project, guests can use the Scheduling Page to book meetings with organizers.

The Scheduler Editor Component includes...

  • Custom event handlers that let you define specific logic or behavior for user actions.
  • Composable components that let you customize how each sub-component is arranged and rendered in the UI.
  • Custom UI stylings that support CSS shadow parts for a higher level of customization.

For more information, see the UI Components references.

Configuration modes

The Scheduling Component supports two configuration modes: app and composable. By default, the Component is set to app mode. This allows it to render all sub-components by default, meaning you can embed the pre-built components in your project with minimal configuration.

You can use the composable mode to customize how the Scheduler Editor Component arranges and renders each sub-component in the UI. In this mode, you can use sub-components as stand-alone components.

For more information, see the Scheduling Component references.

Create a one-time invitation

You can use the Scheduling Component to create and display one-time invitations for events. These invitations have a set date and time, and guests can book the event by entering their contact information.

This 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 user can't go back to the time slot selection page.

<html>
  <body>
    <nylas-scheduling />

    <script type="module">
      import { defineCustomElement } from "https://cdn.jsdelivr.net/npm/@nylas/web-elements@latest/dist/cdn/nylas-scheduling/nylas-scheduling.es.js";

      defineCustomElement();

      const nylasScheduling = document.querySelector('nylas-scheduling');
      nylasScheduling.showBookingForm = true
      
      nylasScheduling.selectedTimeslot = {
        start_time: new Date('2024-02-22T22:12:53+0000'),
        end_time: new Date('2024-02-23T22:14:53+0000')
      }
    </script>
  </body>
</html>   
<NylasScheduling
  mode="app"
  // Set the Scheduler Configuration ID if using public Configuration (`requires_session_auth=false`).
  configurationId={"<SCHEDULER_CONFIGURATION_ID>"}
  // OR set the Scheduler session ID if using private Configuration (`requires_session_auth=true`).
  // sessionId={"<SCHEDULER_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')
    }
  }}
/>

Pre-fill the booking form

You can define bookingInfo to pre-fill the booking form (for example, you can provide the guest's name and email address to make the booking process more convenient). This example pre-fills the booking form with the guest's name, primary email address, secondary email address, and phone number.

<html>
  <body>
    <nylas-scheduling/>

    <script type="module">
      import { defineCustomElement } from "https://cdn.jsdelivr.net/npm/@nylas/web-elements@latest/dist/cdn/nylas-scheduling/nylas-scheduling.es.js";
      
      defineCustomElement();  
      
      const nylasScheduling = document.querySelector('nylas-scheduling');

      nylasScheduling.bookingInfo = {
        primaryParticipant: {
          name: 'John Doe',
          email: 'johndoe@example.com',
        },
        guests: [{
          name: 'Jane Smith',
          email: 'janesmith@example.com'
        }],
        additionalFields: {
          additional_email: {
            value: 'nyla@example.com',
            type: 'email',
          },
          phone_number: {
            value: '1234567890',
            type: 'phone_number'
          }
        },
      };
    </script>
  </body>
</html>   
const bookingInfoData = {
  primaryParticipant: {
    name: 'John Doe',
    email: 'johndoe@example.com',
  },
  guests: [{
    name: 'Jane Smith',
    email: 'janesmith@example.com'
  }],
  additionalFields: {
    additional_email: {
      value: 'xyz@example.com',
      type: 'email',
    },
    phone_number: {
      value: '1234567890',
      type: 'phone_number'
    }
};

<NylasScheduling bookingInfo={bookingInfoData} />

💡 For hosted Scheduling Pages, you can pass query parameters in the URL to pre-fill the booking form.

Skip the booking form

You can set eventOverrides to override the default behavior for the timeslotConfirmed event (proceeding to the booking form page). The following example skips the booking form page and confirms the event after the guest confirms their selected time. After the booking is confirmed, the Scheduling Page displays a "thank you" message.

<html>
  <body>
    <nylas-scheduling />

    <script type="module">  
      import { defineCustomElement } from "https://cdn.jsdelivr.net/npm/@nylas/web-elements@latest/dist/cdn/nylas-scheduling/nylas-scheduling.es.js";

      defineCustomElement();
      
      const nylasScheduling = document.querySelector('nylas-scheduling');

      nylasScheduling.eventOverrides={{
        timeslotConfirmed: (event, connector) => {
          event.preventDefault()
          
          connector.scheduler.bookTimeslot({
            primaryParticipant: {
              name:"John Smith",
              email:"john.smith@example.com"
            }
          })
      }}}
    </script>
  </body>
</html>   
<NylasScheduling 
  configurationId="<SCHEDULER_CONFIGURATION_ID>"
  // OR set the Scheduler session ID if using private Configuration (`requires_session_auth=true`)
  // sessionId="<SCHEDULER_SESSION_ID> 
  mode="app"
  eventOverrides={{
    timeslotConfirmed: (event, connector) => {
      event.preventDefault()

      connector.scheduler.bookTimeslot({
        primaryParticipant: {
          name:"John Smith",
          email:"john.smith@example.com"
        }
      })
    }
  }}
/>

Disable Feedback button

By default, Scheduling Pages include a feedback option that lets users provide feedback or report errors to Nylas. If you want to hide the Feedback button in your UI, set enableUserFeedback to false.

<html>
  <body>
    <nylas-scheduling enable-user-feedback="false"/>
      
    <script type="module">
      // ...Scheduling Page configuration
    </script>
  </body>
</html>   
<NylasScheduling enableUserFeedback={false}
  ...
/>

Arrange and customize sub-components

You can use the composable mode to customize how Scheduler renders each sub-component in the Scheduling Page.

This example creates a date selection page with a panel on either side of the Component. The left panel contains the date picker and locale switch sub-components, and the right panel displays the time slot picker.

<nylas-scheduling 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>
</nylas-scheduling>   
<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

Scheduler's event handlers respond to user actions and control the operations that follow. Each event handler is associated with a specific type of event (for example, bookTimeslot or cancelBooking).

You can use the eventOverrides property to customize the default event handlers to use specific logic or behaviors. For example, you can track user interactions for analytics, update the available time slots when the user selects a date, and much more.

The following example overrides the default timeslotConfirmed handler.

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

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

    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.
      const timeslot = event.detail;

      const bookingData = {
        primaryParticipant: {name: "John Smith", email: "john.smith@example.com"}
        timezone: "America/New_York",
        guests: [{name: "Jane Doe", email: "jane.doe@example.com"}],
        additionalFields: {"key": {value: "", type: ""}},
        timeslot
      };

      nylasConnector.scheduler.bookTimeslot(bookingData).then(bookingResponse => {
        console.log("Booking completed:", bookingResponse);
      }).catch(error => {
        console.error("Booking failed:", error);
      });

      // Send data to analytics service.
      sendToAnalyticsService(event.detail);
    }
  });
<script/>   
<NylasScheduling
  eventOverrides={
    timeslotConfirmed: async (event, connector) => {
      const timeslot = event.detail;

      const bookingData = {
        primaryParticipant: {name: "John Smith", email: "john.smith@example.com"}
        timezone: "America/New_York",
        guests: [{name: "Jane Doe", email: "jane.doe@example.com"}],
        additionalFields: {"key": {value: "", type: ""}},
        timeslot
      };

      connector.scheduler.bookTimeslot(bookingData).then(bookingResponse => {
        console.log("Booking completed:", bookingResponse);
      }).catch(error => {
        console.error("Booking failed:", error);
      });

    ...
    }
  }
/>

The NylasSchedulerConnectorInterface object allows custom event handlers to interact with the following Nylas Scheduler API functions:

  • bookTimeslot
  • cancelBooking
  • getAvailability
  • rescheduleBooking

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 rely on the outcome of other operations.