{"id":11658,"library":"react-calendly","title":"Calendly Integration for React","description":"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.","status":"active","version":"4.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/tcampb/react-calendly","tags":["javascript","react","calendly","component","typescript"],"install":[{"cmd":"npm install react-calendly","lang":"bash","label":"npm"},{"cmd":"yarn add react-calendly","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-calendly","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React applications. Requires >=16.8.0 since v4.0.0.","package":"react","optional":false},{"reason":"Peer dependency for React applications. Requires >=16.8.0 since v4.0.0.","package":"react-dom","optional":false}],"imports":[{"note":"Primary component for embedding Calendly inline. Always use named import.","wrong":"const InlineWidget = require('react-calendly').InlineWidget;","symbol":"InlineWidget","correct":"import { InlineWidget } from 'react-calendly';"},{"note":"Component for a floating Calendly modal. Requires 'rootElement' prop. Use named import.","wrong":"import PopupWidget from 'react-calendly';","symbol":"PopupWidget","correct":"import { PopupWidget } from 'react-calendly';"},{"note":"React hook for listening to Calendly events. Replaced the 'CalendlyEventListener' component in v4.0.0. Use named import.","wrong":"import { CalendlyEventListener } from 'react-calendly';","symbol":"useCalendlyEventListener","correct":"import { useCalendlyEventListener } from 'react-calendly';"}],"quickstart":{"code":"import React from 'react';\nimport { InlineWidget } from 'react-calendly';\n\nconst App = () => {\n  return (\n    <div className=\"App\" style={{ minHeight: '800px', padding: '20px' }}>\n      <h1>Schedule a Meeting</h1>\n      <p>Please use the Calendly widget below to find a convenient time for us to connect.</p>\n      <InlineWidget url=\"https://calendly.com/your_username/30min\" styles={{ height: '600px' }} />\n      <p>We look forward to speaking with you!</p>\n    </div>\n  );\n};\n\nexport default App;\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Migrate from `<CalendlyEventListener>` to `useCalendlyEventListener()` hook for event handling. For example, replace `<CalendlyEventListener onEventScheduled={handler} />` with `useCalendlyEventListener({ onEventScheduled: handler });`.","message":"The `CalendlyEventListener` component was removed in favor of the `useCalendlyEventListener` hook in version `4.0.0`. Direct component usage will result in runtime errors.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your project's `react` and `react-dom` packages are updated to version `16.8.0` or higher to satisfy peer dependency requirements.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always provide `rootElement={document.getElementById('root')}` or another valid DOM element as a prop to `PopupWidget` and `PopupButton`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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')`.","message":"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.","severity":"gotcha","affected_versions":"<4.0.1"},{"fix":"To customize the loading experience, pass your own `LoadingSpinner` React component to the `InlineWidget` or other Calendly components, e.g., `<InlineWidget LoadingSpinner={MyCustomSpinner} ... />`.","message":"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.","severity":"gotcha","affected_versions":">=4.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Replace the `CalendlyEventListener` component with the `useCalendlyEventListener` hook, which is the correct API for event handling since v4.0.0.","cause":"Attempting to use the `CalendlyEventListener` component after `react-calendly` was updated to v4.0.0 or later.","error":"TypeError: (0, react_calendly__WEBPACK_IMPORTED_MODULE_2__.CalendlyEventListener) is not a function"},{"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.","cause":"The `PopupWidget` or `PopupButton` component was not provided with a valid `rootElement` prop, which is required for React's Portal feature.","error":"Invariant Violation: Target container is not a DOM element."},{"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.","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.","error":"Prefill options (e.g., email, guests) are not being applied or show incorrect values."},{"fix":"Update your `react-calendly` package to version v2.2.2 or later to resolve the loading spinner persistence issue.","cause":"This was a known bug in older versions of `react-calendly` (fixed in v2.2.2).","error":"The Calendly loading spinner remains visible even after the widget has loaded."}],"ecosystem":"npm"}