Registry / communication / react-use-intercom

react-use-intercom

library5.5.0jsnpmunverified

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.

communication

npm install react-use-intercom

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-USE-INTERCOM

react-use-intercom

communicationjavascriptv5.5.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

IntercomProvider

✓ import { IntercomProvider } from 'react-use-intercom';

✗ const { IntercomProvider } = require('react-use-intercom');

IntercomProvider is a named export and should be imported using ES Module syntax. It must wrap any components using useIntercom.

useIntercom

✓ import { useIntercom } from 'react-use-intercom';

✗ const { useIntercom } = require('react-use-intercom');

useIntercom is a named export and a React Hook. It must be called from within a React functional component or custom hook.

* as IntercomModule

✓ import * as IntercomModule from 'react-use-intercom';

✗ import IntercomModule from 'react-use-intercom';

While less common, this imports all named exports into a single object. No default export exists.

This code demonstrates how to initialize Intercom using IntercomProvider, boot the messenger, and control its visibility using the useIntercom hook.

import * as React from 'react'; import { IntercomProvider, useIntercom } from 'react-use-intercom'; const INTERCOM_APP_ID = process.env.INTERCOM_APP_ID ?? 'your-intercom-app-id'; const App = () => ( <IntercomProvider appId={INTERCOM_APP_ID}> <HomePage /> </IntercomProvider> ); const HomePage = () => { const { boot, shutdown, hide, show, update, showNewMessage } = useIntercom(); return ( <div> <button onClick={() => boot({ hideDefaultLauncher: false })}>Boot Intercom! ☎️</button> <button onClick={hide}>Hide Messenger</button> <button onClick={show}>Show Messenger</button> <button onClick={() => showNewMessage('Hello there!')}>New Message</button> <button onClick={shutdown}>Shutdown Intercom</button> <p>This button boots Intercom and shows the messenger. Other buttons control its visibility or initiate new conversations.</p> </div> ); }; // To run this in a simple environment, you might need a root element and ReactDOM. // For example, in a Create React App setup: // import ReactDOM from 'react-dom/client'; // const root = ReactDOM.createRoot(document.getElementById('root')); // root.render(<App />);

Debug

Known issues

gotchaWhen 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.

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.

affects: >=5.4.3

gotchaIn 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.

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.

affects: >=1.0.0

gotchaMany 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.

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.

affects: >=1.0.0

gotchaForgetting 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.

fix

Ensure `IntercomProvider` is placed as high as possible in your React component hierarchy, above any components that call `useIntercom`.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: window is not defined

Attempting to access browser-specific APIs (like `window`) during server-side rendering without proper checks.

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.

Error: `useIntercom` must be used within `IntercomProvider`

The `useIntercom` hook was called outside of an `IntercomProvider` context.

fix

Wrap the component that uses `useIntercom` (and its ancestors) with `<IntercomProvider appId="YOUR_APP_ID">...</IntercomProvider>`.

Content Security Policy (CSP) violation: The page’s settings blocked the loading of a resource at...

Your web application's Content Security Policy is preventing Intercom scripts or resources from loading.

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.

TypeError: Cannot read properties of undefined (reading 'boot')

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.

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.

Upgrade

Version history

5.5.0latest on npm

Audit

Dependencies

reactrequiredRequired for React component and hook functionality.

react-domrequiredRequired for rendering React components.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/devrnt/react-use-intercom ↗

packagehttps://www.npmjs.com/package/react-use-intercom ↗