tb-react-live-chat-loader v2.7.6
React Live Chat Loader
An npm module that allows you to mitigate the negative performance and user
experience impact of chat tools. react-live-chat-loader
shows a fake widget
until the page has become idle or users are ready to interact with chat. Currently works with Intercom, Help Scout, Drift, Messenger, Userlike and Chatwoot.
Made by the team at ♠ Calibre, your performance companion.
🖇️ Table of Contents
💡 How it Works
Chat widgets rely heavily on JavaScript which comes at a cost. Given the significant impact that comes from the download, parse, compile and execution of chat JavaScript, React Live Chat Loader implements a "fake", fast loading button and waits for one of the following events before loading the actual widget:
- Person hovers over the fake button
- Person clicks the fake button
- The page has been idle for a significant amount of time
Under the hood React Live Chat Loader makes use of requestIdleCallback
to
track how long the page has been idle for and checks if the person is on a slow
connection (using navigator.connection.effectiveType
) or has data-saver enabled
(using navigator.connection.saveData
) to prevent loading.
⚠️ Please note: Some chat widget providers open automatically based on the people’s interaction from their last session.
📥 Installation
To download react-live-chat-loader run:
npm install --save react-live-chat-loader
Or if you're using yarn, run:
yarn add react-live-chat-loader
🛠 Usage
To allow you to trigger a single live chat within your application, React Live
Chat Loader has a Context Provider
which should be added at the root level of
your application.
You pass your providerKey
and provider
to the LiveChatLoaderProvider
.
For example, to add a LiveChatLoaderProvider
for Help Scout you would do the
following:
import { LiveChatLoaderProvider } from 'react-live-chat-loader'
export default class App extends React.Component {
/* ... */
render() {
return (
<LiveChatLoaderProvider providerKey="asdjkasl123123" provider="helpScout">
/* ... */
</LiveChatLoaderProvider>
)
}
}
You can then include the relevant chat where you would like it to appear.
For example, for Help Scout you would import the HelpScout
component and add it
to your application:
import { HelpScout } from 'react-live-chat-loader'
export default class Index extends React.Component {
/* ... */
render() {
return (
<>
/* ... */
<HelpScout />
</>
)
}
}
To display chat from a custom button you can import the useChat
hook which has the current state of the chat and a function to load the
chat.
import { useChat } from 'react-live-chat-loader'
export const LoadChatButton = () => {
const [state, loadChat] = useChat()
return <button onClick={() => loadChat({ open: true })}>Load Chat</button>
}
Options
You can pass the following props to the LiveChatLoaderProvider
provider:
provider
: Choose fromhelpScout
,intercom
,drift
ormessenger
(see below)providerKey
: Provider API Key (see below)idlePeriod
: How long to wait in ms before loading the provider. Default is2000
. Set to0
to never load. This value is used in asetTimeout
in browsers that don't supportrequestIdleCallback
.beforeInit
: A function to be called after the script has loaded, but before the chat provider has been initialized (optional)onReady
: A function to be called once the script has been loaded, the chat provider has been initialized and is ready for use (optional)
💬 Supported Providers
Currently there are six supported providers:
To use Help Scout import the LiveChatLoaderProvider
and set the provider
prop
as helpScout
and the providerKey
prop as your Beacon API Key.
Then import the HelpScout
component.
import { LiveChatLoaderProvider, HelpScout } from 'react-live-chat-loader'
export default class App extends React.Component {
render() {
return (
<LiveChatLoaderProvider providerKey="asdjkasl123123" provider="helpScout">
/* ... */
<HelpScout />
</LiveChatLoaderProvider>
)
}
}
You can customise the Help Scout beacon by passing the following props to the
HelpScout
component:
color
: The background color of the beaconicon
: Choose frommessage
,antenna
,search
,question
,beacon
zIndex
: Changes the CSS index value of how the Beacon relates to other objectshorizontalPosition
: Choose fromleft
orright
Currently the Help Scout component only supports the icon button style.
To use Intercom import the LiveChatLoaderProvider
and set the provider
prop
as intercom
and the providerKey
prop as your Intercom App ID.
Then import the Intercom
component.
import { LiveChatLoaderProvider, Intercom } from 'react-live-chat-loader'
export default class App extends React.Component {
render() {
return (
<LiveChatLoaderProvider providerKey="asd239" provider="intercom">
/* ... */
<Intercom />
</LiveChatLoaderProvider>
)
}
}
You can customise the color of the Intercom widget by passing a color
prop to
the Intercom
component.
User or Company context data can be set using window.intercomSettings
. See the official Intercom documentation for more details.
To use Messenger, import the LiveChatLoaderProvider
and then set the provider
prop as messenger
and the providerKey
prop as your Facebook Page ID.
If you are using other Facebook features like share, you should set the appID
prop as your Facebook App ID as the Customer Chat SDK includes all the features that Facebook provide.
You can optionally set the locale
prop, the default value is en_US
.
Then import the Messenger
component.
import { LiveChatLoaderProvider, Messenger } from 'react-live-chat-loader'
export default class App extends React.Component {
render() {
return (
<LiveChatLoaderProvider
provider="messenger"
providerKey="111222333444555"
appID="111222333444555"
locale="en_US"
>
/* ... */
<Messenger />
</LiveChatLoaderProvider>
)
}
}
For a list of locale option values, refer to Facebook Localization documentation.
You can customise the Messenger widget by passing the following props to the
Messenger
component:
color
: The theme color of the widgetloggedInGreeting
: The greeting text that will be displayed if the person is currently logged in to Facebook.loggedOutGreeting
: The greeting text that will be displayed if the person is currently not logged in to Facebook.greetingDialogDisplay
: Sets how the greeting dialog will be displayed.greetingDialogDelay
: Sets the number of seconds of delay before the greeting dialog is shown after the plugin is loaded.
For a list of options, refer to Facebook Customer Chat Plugin documentation.
⚠️ Please note: Facebook Messenger will not load on localhost and you will need to configure your domain through the setup wizard in Facebook for it to load correctly.
To use Drift import the LiveChatLoaderProvider
and set the provider
prop
as drift
and the providerKey
prop as your Drift App ID.
Then import the Drift
component.
import { LiveChatLoaderProvider, Drift } from 'react-live-chat-loader'
export default () => (
<LiveChatLoaderProvider providerKey="asdhjg127s1s" provider="drift">
/* ... */
<Drift />
</LiveChatLoaderProvider>
)
You can customise the Drift Messenger by passing the following props to the
Drift
component:
color
: The background color of the messengericon
: Choose fromA
,B
,C
,D
; you're presented with these preset icons when signing up for Drift, or in the "Drift Widget > Design > Widget icon" entry under the "App Settings" header on the Drift settings page.
To use Userlike import the LiveChatLoaderProvider
and set the provider
prop
as userlike
and the providerKey
prop as your Userlike Widget secret.
Then import the Userlike
component.
import { LiveChatLoaderProvider, Userlike } from 'react-live-chat-loader'
export default () => (
<LiveChatLoaderProvider
providerKey="x014e93c288445c0bf6f8a378a0b1af8e6e1125t71634124a88fe63e38hme701"
provider="userlike"
>
/* ... */
<Userlike />
</LiveChatLoaderProvider>
)
You can customise the Userlike Widget by passing the following props to the
Userlike
component:
color
: The contrasting color, can beblack
orwhite
.backgroundColor
: The main colorposition
: The button position, can beright
orleft
.vOffset
: The amount of vertical margin.hOffset
: The amount of horizontal margin.style
: The shape style, can beround
orsquare
.
To use Chatwoot import the LiveChatLoaderProvider
and set the provider
prop
as chatwoot
and the providerKey
prop as your Chatwoot secret.
You can optionally set the locale
and baseUrl
props.
Then import the Chatwoot
component.
import { LiveChatLoaderProvider, Chatwoot } from 'react-live-chat-loader'
export default () => (
<LiveChatLoaderProvider
providerKey="E33wn9ftxMDHZx18AaBkfPvY"
provider="chatwoot"
>
/* ... */
<Chatwoot />
</LiveChatLoaderProvider>
)
You can customise the Chatwoot Widget by passing the following props to the
Chatwoot
component:
color
: The background color, set to same color value you choose in Chatwoot dashboard.
➕ Adding a Provider
To add a new live chat provider, follow the steps in Contributing: Adding a Provider.
🙌 Contributing
Happy to hear you’re interested in contributing to React Live Chat Loader! Please find our contribution guidelines here.
🖥️ Examples
- react-live-chat-loader-example-app: example Next.js application
📚 Resources
- How to avoid performance regressions when using live chat tools
- Reducing the Intercom Messenger bundle size by 65%
✨ Contributors
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!