Lack of documentation about chat-widget-adapters HOT 1 CLOSED

Hello @syn6UK 👋

Please use provided issue templates and do not skip the proposed structure. They are defined for the purpose to point what information we need in order to properly take care of your request. Link for reference: Feature request.

Answering your question. The documentation for @livechat/widget-react package directly explains how the LiveChatWidget should be used inside React application.

The main goal of the Chat Widget Adapters project is to provide a framework-aware implementation for using our Chat Widget without the need to directly access our JS API. But the JS API is an option that is always available to you if you wish to integrate the widget that way.

Being a framework-aware implementation each adapter integrates the Chat Widget with a framework-specific reactivity model and best practices. In the case of React, we expose the component LiveChatWidget which accepts a set of props described in the documentation: README.md#props. Props are split into two categories: Configuration and Event handlers.

Using React's definition/approach to how the UI should be rendered it's most commonly represented as: The UI is a result of component function being called with passed properties. That way we should always render Chat Widget in the same state while the same properties are provided. All of the props available on LiveChatWidget component are properly reactive and you can steer the behavior of the widget by simply changing their values, the same way as you do with many other React components.

An example implementation of controlled widget visibility comes down to the concept of Controlled Component documented directly on official React docs. Properties of LiveChatComponent being used are also described in the project's documentation: visibility, onVisibilityChanged.

import * as React from 'react'
import { LiveChatWidget } from '@livechat/widget-react'
import type { WidgetState, EventHandlerPayload } from '@livechat/widget-react'

function App() {
  const [visibility, setVisibility] = React.useState<WidgetState['visibility']>('minimized')

  function handleSelectChange(event: React.ChangeEvent<HTMLSelectElement>) {
    setVisibility(event.target.value as WidgetState['visibility'])
  }

  function handleVisibilityChanged({ visibility }: EventHandlerPayload<'onVisibilityChanged'>) {
    setVisibility(visibility)
  }

  return (
    <main>
      <div>
        <label htmlFor="visibility">Widget visibility: </label>
        <select id="visibility" value={visibility} onChange={handleSelectChange}>
          <option>minimized</option>
          <option>maximized</option>
          <option>hidden</option>
        </select>
      </div>
      <LiveChatWidget license="12332502" visibility={visibility} onVisibilityChanged={handleVisibilityChanged} />
    </main>
  )
}

Here is a video showcasing the example:

from chat-widget-adapters.