Calendly Integration for React

4.4.0 · active · verified Sun Apr 19

react-calendly is a React component library designed to simplify the integration of Calendly scheduling pages into React applications. It provides high-level components like InlineWidget, PopupWidget, and PopupButton for embedding various Calendly layouts, as well as the useCalendlyEventListener hook for programmatic interaction with Calendly events within the iframe. The library is actively maintained, with its current stable version being 4.4.0. Releases occur frequently, typically addressing bug fixes and introducing new prefill options or minor feature enhancements. Key differentiators include its abstraction over raw Calendly embed scripts, direct support for React's component lifecycle and hooks, and built-in handling for common embedding challenges like loading states and event listening. It relies on React's Portal feature for modal rendering, requiring explicit rootElement configuration for popup widgets.

Common errors

```
TypeError: (0, react_calendly__WEBPACK_IMPORTED_MODULE_2__.CalendlyEventListener) is not a function
```
cause Attempting to use the `CalendlyEventListener` component after `react-calendly` was updated to v4.0.0 or later.

fix Replace the `CalendlyEventListener` component with the `useCalendlyEventListener` hook, which is the correct API for event handling since v4.0.0.
```
Invariant Violation: Target container is not a DOM element.
```
cause The `PopupWidget` or `PopupButton` component was not provided with a valid `rootElement` prop, which is required for React's Portal feature.

fix Ensure you pass a valid DOM element to the `rootElement` prop, typically `rootElement={document.getElementById('root')}` or the ID of your application's root div.
```
Prefill options (e.g., email, guests) are not being applied or show incorrect values.
```
cause The prefill parameters might be improperly formatted, not URI-encoded, or there might be a bug in older library versions. This was specifically addressed in v4.0.1.

fix Upgrade `react-calendly` to v4.0.1 or newer. Additionally, ensure that any custom prefill values are correctly URI-encoded, especially for special characters.
```
The Calendly loading spinner remains visible even after the widget has loaded.
```
cause This was a known bug in older versions of `react-calendly` (fixed in v2.2.2).

fix Update your `react-calendly` package to version v2.2.2 or later to resolve the loading spinner persistence issue.

Warnings

breaking The `CalendlyEventListener` component was removed in favor of the `useCalendlyEventListener` hook in version `4.0.0`. Direct component usage will result in runtime errors.
Fix: Migrate from `<CalendlyEventListener>` to `useCalendlyEventListener()` hook for event handling. For example, replace `<CalendlyEventListener onEventScheduled={handler} />` with `useCalendlyEventListener({ onEventScheduled: handler });`.
breaking Version `4.0.0` updated peer dependencies, requiring `react` and `react-dom` versions `>=16.8.0`. Applications using older React versions will encounter peer dependency warnings or runtime issues.
Fix: Ensure your project's `react` and `react-dom` packages are updated to version `16.8.0` or higher to satisfy peer dependency requirements.
gotcha When using `PopupWidget` or `PopupButton`, the `rootElement` prop is mandatory. These components leverage React Portals, which require a specific DOM node to attach the modal to, otherwise, they will fail to render or throw errors.
Fix: Always provide `rootElement={document.getElementById('root')}` or another valid DOM element as a prop to `PopupWidget` and `PopupButton`.
gotcha Prefill options, particularly `email` and `guests`, might not work correctly if they contain special characters or are improperly encoded. A fix was introduced in `v4.0.1` to address encoding issues.
Fix: Update to `react-calendly@4.0.1` or newer. For custom prefill options, ensure values are URI-encoded before passing them, for example, `encodeURIComponent('my+email@example.com')`.
gotcha While `react-calendly` provides a default loading spinner, customizing it requires passing a `LoadingSpinner` React component as a prop. Developers might miss this option, sticking with the default spinner.
Fix: To customize the loading experience, pass your own `LoadingSpinner` React component to the `InlineWidget` or other Calendly components, e.g., `<InlineWidget LoadingSpinner={MyCustomSpinner} ... />`.

Install

npm install react-calendly npm
yarn add react-calendly yarn
pnpm add react-calendly pnpm

Imports

InlineWidget

wrong:

const InlineWidget = require('react-calendly').InlineWidget;

correct:

import { InlineWidget } from 'react-calendly';

Primary component for embedding Calendly inline. Always use named import.

PopupWidget
wrong:
```
import PopupWidget from 'react-calendly';
```
correct:
```
import { PopupWidget } from 'react-calendly';
```
Component for a floating Calendly modal. Requires 'rootElement' prop. Use named import.
useCalendlyEventListener
wrong:
```
import { CalendlyEventListener } from 'react-calendly';
```
correct:
```
import { useCalendlyEventListener } from 'react-calendly';
```
React hook for listening to Calendly events. Replaced the 'CalendlyEventListener' component in v4.0.0. Use named import.

Quickstart

This quickstart embeds an InlineWidget for a Calendly scheduling page, demonstrating basic usage within a React component. Make sure to replace the placeholder URL with your actual Calendly link.

import React from 'react';
import { InlineWidget } from 'react-calendly';

const App = () => {
  return (
    <div className="App" style={{ minHeight: '800px', padding: '20px' }}>
      <h1>Schedule a Meeting</h1>
      <p>Please use the Calendly widget below to find a convenient time for us to connect.</p>
      <InlineWidget url="https://calendly.com/your_username/30min" styles={{ height: '600px' }} />
      <p>We look forward to speaking with you!</p>
    </div>
  );
};

export default App;

view raw JSON →