npm package: @livechat/ui-kit
Description: Chat UI Kit
Latest version: 0.5.0-40

Hi there! 👋

Welcome to the **React Chat UI Kit** docs.

React Chat UI Kit is a set of **React components** to easily build nice-looking
chat windows.

<aside class="note">React is a JavaScript library for building user interfaces. For more
details, head to the [React official website](https://reactjs.org/).</aside>

## Key principles

Our aim was to create a complex set of components to solve common React chat
apps implementation issues.

With React Chat UI Kit, we want to:

- apply good user experience solutions,
- allow rich theme customization,
- provide maximum components flexibility,
- cover various communication needs.

## Use cases

You can use React Chat UI Kit for two main purposes:

- building a custom chat widget,
- building an app that handles chats view (e.g. a LiveChat archive viewer).

<a name="examples"></a>

## Examples

We have created a sample chat widget, integrated with
[LiveChat](https://www.livechatinc.com/) and
[BotEngine](https://www.botengine.ai/):

![Sample Chat Widget](https://static.livechatinc.com/1520/P10DCF6MPV/18c93d96c765984da3d29417915b9ac3/sample-chat-widget.png)

- [View sample chat widget source at Github](https://github.com/livechat/chat-widget-sample)
- [Preview sample at CodeSandbox](https://codesandbox.io/s/github/livechat/chat-widget-sample/tree/master/)

In this widget, [BotEngine](https://www.botengine.ai/) handles the incoming
chats. When the bot returns `LiveChat.transfer` action, the chat is transferred
to a human agent together with the transcript of the initial conversation with
the bot.

<aside class="note">The sample app uses
[Visitor SDK](https://docs.livechatinc.com/visitor-sdk/) to communicate with
LiveChat and [the API](https://docs.botengine.ai/api/introduction) to connect
with BotEngine.</aside>

# Getting started

## Install React Chat UI Kit

### Using npm

To install React Chat UI Kit with npm, run the following command:

`npm install --save @livechat/ui-kit`
This section will guide you through the basic concepts of LiveChat UI Kit, theme
structure and components.

## The basics

This is the basic app structure:

```html
import { ThemeProvider } from '@livechat/ui-kit'
<ThemeProvider>
  { /* other components /* }
</ThemeProvider>
```

The whole app should always be wrapped in `<ThemeProvider>` component.

You can either pass your own theme configuration using `theme` props (see "Theme
structure" section below), or use the default looks. Your theme configuration
will be **merged with the default theme**. What does it mean? For example, you
don't have to build the whole object if you only want to change the color of a
single element. All you have to do is to pass the relevant property (with the
color change) &mdash; all other elements will pick up the default styles.

## Theme structure

Each LiveChat widget theme is basically a **JavaScript object**. A **theme
object** groups all properties of a single theme.

Theme objects consist of the following elements:

<table>
    <thead>
        <tr>
            <th>Property name</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>vars</code></td>
            <td>CSS variables available to be used in the components. By default there are 3 colors defined: "primary-color", "secondary-color", and "tertiary-color", but you can add more (and not only colors, of course!).</td>
        </tr>
        <tr>
            <td><code>[COMPONENT_NAME]</code></td>
            <td>An object with component's settings. See "Theme components" section below for details.</td>
        </tr>
    </tbody>
</table>

You can pass custom theme objects to `ThemeProvider` using `theme` property (see
"Variables" section below for code example).

## Variables

Like popular CSS preprocessors, React Chat UI Kit supports **variables**. It
means that you can first define custom properties in `vars` section, and then
reuse them throughout your theme. To refer to a variable, use its property key
preceded by -- and wrapped in a var function. For example, if your variable's property key is primary-color, you will use it as follows: `var(--primary-color)`.
You can read more about CSS variables [here](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables).

<aside class="note">React Chat UI Kit can only parse the variables defined in `vars` section. It doesn't support [fallback values](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables#Custom_Property_fallback_values).</aside>

In the example below, `primary-color`, `secondary-color`, `tertiary-color` and
`avatar-border-color` are variables:

```html
const theme = { vars: { 'primary-color': '#427fe1', 'secondary-color':
'#fbfbfb', 'tertiary-color': '#fff', 'avatar-border-color': 'blue', }, AgentBar:
{ Avatar: { size: '42px', }, css: { backgroundColor: 'var(--secondary-color)',
borderColor: 'var(--avatar-border-color)', } }, Message: { css: { fontWeight:
'bold', }, }, }
```

## Theme components

**Components**, or the **elements of the LiveChat widget**, are the heart of
LiveChat UI Kit. Think of them as of building blocks that a chat window is made
of: agent bar, avatars, input field, buttons, etc.

You can modify a component by placing its customization object in your theme
object. To do so, add a new property to your theme object. This property should
consist of component's name and an object as its value.

On the root level of this object, there are component's properties (every
component has its own list of style properties) and a `css` property, where you
can place CSS declarations:

```html
{ vars: { 'primary-color': 'red', }, Avatar: { size: '40px', // special Avatar's
property, supported by this component css: { // css object with any CSS
properties borderColor: 'blue', }, }, TextComposer: { css: { 'color': '#000', },
}, }
```

### Nested components

You can also customize components placed inside other components. For example:
"Set the size of any avatar to 30px and set the border color to blue, but only
`Avatars` placed inside `AgentBar` components should have a 1px red border and green
background". To do this, add `Avatar` section inside `AgentBar` with proper
customization:

```html
{ Avatar: { size: '40px', // special Avatar's property, supported by this
component css: { // css object with any CSS properties borderColor: 'blue', },
}, AgentBar: { Avatar: { css: { // you can place there any CSS properties
border: '1px solid red', backgroundColor: 'green', } }, }, }
```
Subscribe to
[LiveChat Developers Newsletter](https://developers.livechatinc.com/newsletter/)
to be notified about changes in React Chat UI Kit.

#### [v0.1.0] - 3.01.2018

Use CSS variables syntax in themes instead of custom syntax

#### [v0.0.9] - 2.01.2018

Fix onScroll MessageList callback

#### [v0.0.8] - 2.01.2018

Fix onSeen message callback

#### [v0.0.6] - 22.12.2017

Fix library peer dependencies, docs improvements

#### [v0.0.5] - 21.12.2017

First public release