{"id":11899,"library":"react-use-intercom","title":"React Intercom Integration with Hooks","description":"react-use-intercom is a specialized React library that provides a hook-driven abstraction layer for integrating the Intercom chat widget into web applications. Currently at version 5.5.0, it maintains an active and agile release cadence, frequently publishing minor and patch updates to support new IntercomJS features, address bugs, and improve compatibility. Key differentiators include its adherence to modern React patterns by leveraging hooks, full TypeScript support for enhanced developer experience, a minimal bundle size with no external dependencies, and built-in safeguards designed to prevent common issues in Server-Side Rendering (SSR) environments like Next.js and Gatsby. It also allows for seamless integration with existing Intercom instances, such as those loaded via Segment. The library aims for a direct, one-to-one mapping of Intercom's vanilla JavaScript API methods to simplify usage while maintaining full access to Intercom's capabilities. Developers should note that many issues might stem from the underlying IntercomJS library itself.","status":"active","version":"5.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/devrnt/react-use-intercom","tags":["javascript","react","reactjs","intercom","intercomjs","react-intercom","intercom-react","typescript","react-hooks"],"install":[{"cmd":"npm install react-use-intercom","lang":"bash","label":"npm"},{"cmd":"yarn add react-use-intercom","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-use-intercom","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for React component and hook functionality.","package":"react","optional":false},{"reason":"Required for rendering React components.","package":"react-dom","optional":false}],"imports":[{"note":"IntercomProvider is a named export and should be imported using ES Module syntax. It must wrap any components using useIntercom.","wrong":"const { IntercomProvider } = require('react-use-intercom');","symbol":"IntercomProvider","correct":"import { IntercomProvider } from 'react-use-intercom';"},{"note":"useIntercom is a named export and a React Hook. It must be called from within a React functional component or custom hook.","wrong":"const { useIntercom } = require('react-use-intercom');","symbol":"useIntercom","correct":"import { useIntercom } from 'react-use-intercom';"},{"note":"While less common, this imports all named exports into a single object. No default export exists.","wrong":"import IntercomModule from 'react-use-intercom';","symbol":"* as IntercomModule","correct":"import * as IntercomModule from 'react-use-intercom';"}],"quickstart":{"code":"import * as React from 'react';\nimport { IntercomProvider, useIntercom } from 'react-use-intercom';\n\nconst INTERCOM_APP_ID = process.env.INTERCOM_APP_ID ?? 'your-intercom-app-id';\n\nconst App = () => (\n  <IntercomProvider appId={INTERCOM_APP_ID}>\n    <HomePage />\n  </IntercomProvider>\n);\n\nconst HomePage = () => {\n  const { boot, shutdown, hide, show, update, showNewMessage } = useIntercom();\n\n  return (\n    <div>\n      <button onClick={() => boot({ hideDefaultLauncher: false })}>Boot Intercom! ☎️</button>\n      <button onClick={hide}>Hide Messenger</button>\n      <button onClick={show}>Show Messenger</button>\n      <button onClick={() => showNewMessage('Hello there!')}>New Message</button>\n      <button onClick={shutdown}>Shutdown Intercom</button>\n      <p>This button boots Intercom and shows the messenger. Other buttons control its visibility or initiate new conversations.</p>\n    </div>\n  );\n};\n\n// To run this in a simple environment, you might need a root element and ReactDOM.\n// For example, in a Create React App setup:\n// import ReactDOM from 'react-dom/client';\n// const root = ReactDOM.createRoot(document.getElementById('root'));\n// root.render(<App />);\n","lang":"typescript","description":"This code demonstrates how to initialize Intercom using IntercomProvider, boot the messenger, and control its visibility using the useIntercom hook."},"warnings":[{"fix":"Refer to Intercom's documentation for required CSP directives and ensure your server-side rendering or build process correctly injects nonces into the Intercom script tags if used.","message":"When deploying with a Content Security Policy (CSP), ensure that your policy allows script sources from Intercom's domains. Recent versions (>=5.4.3) added support for nonces, but proper CSP configuration is still essential for the Intercom widget to load and function correctly.","severity":"gotcha","affected_versions":">=5.4.3"},{"fix":"Place IntercomProvider high in your component tree and ensure any custom logic interacting with `window.Intercom` is wrapped in `typeof window !== 'undefined'` checks or executed in `useEffect` hooks.","message":"In Server-Side Rendering (SSR) environments like Next.js or Gatsby, direct manipulation of the `window` object will cause 'window is not defined' errors. While `react-use-intercom` includes safeguards, ensure you are mindful of client-side-only code and potentially deferring Intercom operations to the browser environment.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the official Intercom documentation and community forums (community.intercom.com) for issues related to Intercom's core behavior, API limits, or configuration rather than solely focusing on the React wrapper.","message":"Many issues encountered with `react-use-intercom` might originate from the underlying IntercomJS library itself, not the React wrapper. The library provides a direct abstraction, so understanding vanilla Intercom functionality is crucial for debugging complex issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `IntercomProvider` is placed as high as possible in your React component hierarchy, above any components that call `useIntercom`.","message":"Forgetting to wrap your application or relevant component tree with `IntercomProvider` will result in `useIntercom` not being able to find the Intercom context, leading to runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure code interacting with `window` is executed only in the browser context. `react-use-intercom` generally handles this, but custom logic may require `typeof window !== 'undefined'` checks or `useEffect` for client-side execution.","cause":"Attempting to access browser-specific APIs (like `window`) during server-side rendering without proper checks.","error":"ReferenceError: window is not defined"},{"fix":"Wrap the component that uses `useIntercom` (and its ancestors) with `<IntercomProvider appId=\"YOUR_APP_ID\">...</IntercomProvider>`.","cause":"The `useIntercom` hook was called outside of an `IntercomProvider` context.","error":"Error: `useIntercom` must be used within `IntercomProvider`"},{"fix":"Update your CSP to allow `script-src`, `style-src`, `connect-src`, and other necessary directives from Intercom's domains. For dynamic script injection, you might need to use a `nonce` attribute for scripts.","cause":"Your web application's Content Security Policy is preventing Intercom scripts or resources from loading.","error":"Content Security Policy (CSP) violation: The page’s settings blocked the loading of a resource at..."},{"fix":"Verify that `IntercomProvider` is correctly initialized with an `appId` and that `useIntercom` is called within a functional component rendered under `IntercomProvider`. Ensure `IntercomProvider` has had time to initialize on the client side, especially in complex hydration scenarios.","cause":"The `boot` method (or any other method from `useIntercom`) was called on an undefined object, likely due to `IntercomProvider` not being ready or `useIntercom` being called too early or out of context.","error":"TypeError: Cannot read properties of undefined (reading 'boot')"}],"ecosystem":"npm"}