react-live-chat-loader
v2.11.0TypeScript
Implement live chat in your react app without taking a performance hit.
13.8K/weekUpdated 11 months agoMITUnpacked: 706.1 KB
Published by calibreapp.com
npm install react-live-chat-loaderReact 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, Front, Chatwoot, Hubspot and Adobe Dynamic Chat
Made by the team at ♠ Calibre, your performance companion.
> [!IMPORTANT]
> This project is looking for collaborators, maintainers and/or new stewardship. Read more.
Since introducing react-live-chat-loader in 2019 we've welcomed the addition of several chat provider tools, with thanks to numerous contributors. As a group the Calibre team have taken this library as far as we can, and we're looking for someone to take the reigns. If you, your buddies or team can help, please create a new issue to start discussion. 💬
🖇️ Table of Contents
1. How it Works
2. Installation
3. Usage
4. Supported Providers
5. Adding a Provider
6. Examples
7. Contributing
8. Resources
9. License
💡 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:
``bash`
npm install --save react-live-chat-loader
Or if you're using yarn, run:
`bash`
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:
`jsx
import { LiveChatLoaderProvider } from 'react-live-chat-loader'
export default class App extends React.Component {
/ ... /
render() {
return (
/ ... /
)
}
}
`
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:
`jsx
import { HelpScout } from 'react-live-chat-loader'
export default class Index extends React.Component {
/ ... /
render() {
return (
<>
/ ... /
)
}
}
`
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.
`jsx
import { useChat } from 'react-live-chat-loader'
export const LoadChatButton = () => {
const [state, loadChat] = useChat()
return
}
`
$3
You can pass the following props to the LiveChatLoaderProvider provider:
- provider: Choose from helpScout, intercom, drift, front or messenger (see below)providerKey
- : Provider API Key (see below)idlePeriod
- : How long to wait in ms before loading the provider. Default is2000
. Set to 0 to never load. This value is used in a setTimeout inrequestIdleCallback
browsers that don't support .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 eight supported providers:
Help Scout
To use Help Scout import the LiveChatLoaderProvider and set the provider prophelpScout
as and the providerKey prop as your Beacon API Key.
Then import the HelpScout component.
`jsx
import { LiveChatLoaderProvider, HelpScout } from 'react-live-chat-loader'
export default class App extends React.Component {
render() {
return (
/ ... /
)
}
}
`
You can customise the Help Scout placeholder by passing the following props to the
HelpScout component:
- color: The background color of the placeholdericon
- : Choose from message, antenna, search, question, beacon
- : Changes the CSS index value of how the placeholder relates to other objectshorizontalPosition
- : Choose from left or right
- : Class to be added to the placeholder element, defaults to live-chat-loader-placeholder
Currently the Help Scout component only supports the icon button style.
Intercom
To use Intercom import the LiveChatLoaderProvider and set the provider propintercom
as and the providerKey prop as your Intercom App ID.
Then import the Intercom component.
`jsx
import { LiveChatLoaderProvider, Intercom } from 'react-live-chat-loader'
export default class App extends React.Component {
render() {
return (
/ ... /
)
}
}
`
You can customise the Intercom placeholder icon by passing the following props to the Intercom component:
- color: The background color of the placeholder widgetcontainerClass
- : Class to be added to the placeholder element, defaults to live-chat-loader-placeholder
- : Override the default Intercom icon, can be any JSX element.
Messenger Settings, User context and Company context settings can be set using window.intercomSettings. See the official Intercom documentation for more details.
Messenger
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.
`jsx
import { LiveChatLoaderProvider, Messenger } from 'react-live-chat-loader'
export default class App extends React.Component {
render() {
return (
providerKey="111222333444555"
appID="111222333444555"
locale="en_US"
>
/ ... /
)
}
}
`
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 isgreetingDialogDisplay
currently not logged in to Facebook.
- : 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.containerClass
- : Class to be added to the placeholder element, defaults to live-chat-loader-placeholder
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.
Drift
To use Drift import the LiveChatLoaderProvider and set the provider propdrift
as and the providerKey prop as your Drift App ID.
Then import the Drift component.
`jsx
import { LiveChatLoaderProvider, Drift } from 'react-live-chat-loader'
export default () => (
/ ... /
)
`
You can customise the Drift placeholder by passing the following props to the
Drift component:
- color: The background color of the placeholdericon
- : Choose from A, 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.containerClass
- : Class to be added to the placeholder element, defaults to live-chat-loader-placeholder
Userlike
To use Userlike import the LiveChatLoaderProvider and set the provider propuserlike
as and the providerKey prop as your Userlike Widget secret.
Then import the Userlike component.
`jsx
import { LiveChatLoaderProvider, Userlike } from 'react-live-chat-loader'
export default () => (
provider="userlike"
>
/ ... /
)
`
You can customise the Userlike placeholder by passing the following props to the
Userlike component:
- color: The contrasting color, can be black or white.backgroundColor
- : The main colorposition
- : The button position, can be right or left.vOffset
- : The amount of vertical margin.hOffset
- : The amount of horizontal margin.style
- : The shape style, can be round or square.containerClass
- : Class to be added to the placeholder element, defaults to live-chat-loader-placeholder
Chatwoot
To use Chatwoot import the LiveChatLoaderProvider and set the provider propchatwoot
as and the providerKey prop as your Chatwoot secret.
You can optionally set the locale and baseUrl props.
Then import the Chatwoot component.
`jsx
import { LiveChatLoaderProvider, Chatwoot } from 'react-live-chat-loader'
export default () => (
provider="chatwoot"
>
/ ... /
)
`
You can customise the Chatwoot placeholder by passing the following props to the
Chatwoot component:
- color: The background color, set to same color value you choose in Chatwoot dashboard.containerClass
- : Class to be added to the placeholder element, defaults to live-chat-loader-placeholder
Front
To use Front import the LiveChatLoaderProvider and set the provider propfront
as and the providerKey prop as your Front Chat chatId.
Then import the Front component.
`jsx
import { LiveChatLoaderProvider, Front } from 'react-live-chat-loader'
export default () => {
return (
provider="front"
>
/ ... /
)
}
`
You can customise the Front placeholder icon by passing the following props to the Front component:
- color: The background color of the placeholder widget.containerClass
- : Class to be added to the placeholder element, defaults to live-chat-loader-placeholder
See the official Front documentation for more details.
Hubspot
To use Hubspot import the LiveChatLoaderProvider and set the provider prophubSpot
as and the providerKey prop as your Hubspot API Key.
Then import the Hubspot component.
`jsx
import { LiveChatLoaderProvider, Hubspot } from 'react-live-chat-loader'
export default class App extends React.Component {
render() {
return (
/ ... /
)
}
}
`
You can customise the Hubspot placeholder by passing the following props to the
Hubspot component:
- backgroundColor: The background color of the placeholderloader
- : A react component shown while the Hubspot libraries are loading
Adobe Dynamic Chat
To use Adobe Dynamic Chat import the LiveChatLoaderProvider and set the provider propadobeDynamicChat
as and the props for your instance as found in your Chatbot settings > Installation > Javascript snippet.
For example, your script URL will look something like this:
Then import the AdobeDynamicChat component.
`jsx
import { LiveChatLoaderProvider, AdobeDynamicChat } from 'react-live-chat-loader'
export default class App extends React.Component {
render() {
return (
instanceId="yourinstance" // Use "instanceId" query parameter found in script URL
env="prod" // Use "env" query parameter found in script URL
geo="va7" // Use "geo" query parameter found in script URL
provider="adobeDynamicChat"
>
/ ... /
)
}
}
`
You can customise the Adobe Dynamic Chat placeholder icon by passing the following props to the AdobeDynamicChat component:
- color: The background color of the placeholder widgetcontainerClass
- : Class to be added to the placeholder element, defaults to live-chat-loader-placeholder
- : Override the default Adobe Dynamic Chat icon, can be any JSX element.
➕ Adding a Provider
To add a new live chat provider, follow the steps in Contributing: Adding a Provider.
🖥️ Examples
The website directory of this repository includes a Next.js app with example implementations of all currently supported providers.
For the initial setup of the example app, be sure first to run npm install + npm run build in the root level of the repository before running npm install in the website directory.
The following scripts in the example app will then be available:
- npm run dev (run a local server)npm run build
- (run next build)npm run start` (run next start)
-
Visit react-live-chat-loader.vercel.app for a hosted version of the example app.
> 📝 Note that some providers require safe-listed, publicly accessible domains served over HTTPS — a service like ngrok can help achieve this locally.
🙌 Contributing
Happy to hear you’re interested in contributing to React Live Chat Loader! Please find our contribution guidelines here.
$3
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
📚 Resources
- How to avoid performance regressions when using live chat tools
- Reducing the Intercom Messenger bundle size by 65%
💼 License
This project is MIT licensed.