Skip to content

Commit 3df3e53

Browse files
tjtanjintjtanjin
committed
docs: Minor updates
1 parent 111734a commit 3df3e53

File tree

6 files changed

+228
-215
lines changed

6 files changed

+228
-215
lines changed

‎docs/api/events.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,7 @@ keywords: [react, chat, chatbot, chatbotify]
77

88
# Events
99

10-
This page documents all available `events` emitted by the chatbot that may be listened on. Note that events are an **opt-in feature** (i.e. it is disabled by default), as they should not be required for a vast majority of users. Events should be enabled for the following reasons:
11-
- You wish to execute certain application logic on specific chatbot events (e.g. log messages from chatbot)
12-
- You are using [**plugins**](/concepts/plugins) that relies on events emitted by the chatbot (you should refer to the plugin documentation for what events are needed)
10+
This page documents all available [`events`](/concepts/events) emitted by the chatbot that may be listened on.
1311

1412
:::tip Tip
1513
Before adding your own listeners with custom logic for events, it may be helpful to lookup existing [**plugins**](/concepts/plugins) in case there's already a solution out there (e.g. [**input-validator**](https://github.com/react-chatbotify-plugins/input-validator) plugin).

‎docs/api/hooks.md

Lines changed: 1 addition & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -7,75 +7,12 @@ keywords: [react, chat, chatbot, chatbotify]
77

88
# Hooks
99

10-
This page documents all the available custom `hooks` provided by the library. These hooks allow you to interact (externally from your own components) with various parts of the chatbot, such as **toggling audio**, **handling messages**, and **controlling the chat window state**!
10+
This page documents all the available custom `hooks` provided by the library.
1111

1212
:::tip Tip
1313
Hooks are only relevant if you intend to interact with the chatbot functionalities (e.g. toggle audio or chat window) from **outside the chatbot and within your own component**. If you have no such use case, you may skip hooks entirely!
1414
:::
1515

16-
Note that in order to import and use these custom hooks within your components, you first need to import `ChatBotProvider` and nest your components as its children. We'll look at 2 scenarios below.
17-
18-
19-
**Scenario 1:** If you have no need for custom hooks, then you **do not need** to import `ChatBotProvider` and can simply use `ChatBot`. This is likely the scenario for a vast majority of users:
20-
21-
```jsx title=MyComponent.js
22-
import ChatBot from "react-chatbotify";
23-
24-
const MyComponent = () => {
25-
return (
26-
<ChatBot/> {/* no custom hooks needed */}
27-
);
28-
};
29-
```
30-
31-
**Scenario 2:** If you require custom hooks to interact with the chatbot (e.g. toggle audio) from within your own components, you need to import `ChatBotProvider` and ensure that your components that need the hooks are nested within it:
32-
33-
```jsx title=MyComponent.js
34-
import ChatBot, { ChatBotProvider } from "react-chatbotify";
35-
36-
const MyComponent = () => {
37-
return (
38-
<>
39-
<MyNotNestedComponent> {/* unable to access custom hooks */}
40-
<ChatBotProvider>
41-
<MyNestedComponent> {/* able to access custom hooks (e.g. useAudio) */}
42-
<ChatBot/>
43-
</ChatBotProvider>
44-
</>
45-
);
46-
};
47-
```
48-
49-
```jsx title=MyNestedComponent
50-
import { useAudio } from "react-chatbotify";
51-
52-
const MyNestedComponent = () => {
53-
// can use custom hook
54-
const { toggleAudio } = useAudio();
55-
56-
return (
57-
<button onClick={toggleAudio}></button>
58-
)
59-
};
60-
61-
const MyNotNestedComponent = () => {
62-
// error, cannot use custom hook since outside of ChatBotProvider
63-
const { toggleAudio } = useAudio();
64-
65-
return (
66-
<button onClick={toggleAudio}></button>
67-
)
68-
};
69-
```
70-
71-
:::warning Warning
72-
It is a common mistake to import these custom hooks from a component outside of `<ChatBotProvider>`. If you're running into issues, make sure to check that your component is nested properly as a child of `<ChatBotProvider>`!
73-
:::
74-
75-
:::tip Tip
76-
An extensive example featuring how various hooks may be used can be found [**here**](/examples/custom_hooks).
77-
:::
78-
7916
## Overview
8017

8118
Below is a list of available hooks along with a brief description for each of them:

‎docs/concepts/events.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
sidebar_position: 6
3+
title: Events
4+
description: Understanding chatbot events and how to use them.
5+
keywords: [react, chat, chatbot, chatbotify, events, concepts]
6+
---
7+
8+
# Events
9+
10+
[**Custom events**](/api/events) in React ChatBotify provide a way for your application to react to specific occurrences within the chatbot. They are an opt-in feature, meaning all events are disabled by default and individual events should be enabled only when necessary.
11+
12+
## Overview
13+
14+
The chatbot can emit various events throughout its lifecycle and during user interactions. Your application can "listen" for these events and execute a callback function (handler) when an event occurs. You might want to use events if:
15+
16+
* You need to execute custom logic in your application when certain things happen in the chatbot (e.g., logging messages, tracking user interactions).
17+
* You are developing or using [**plugins**](/concepts/plugins) that rely on the chatbot emitting specific events (refer to the plugin's documentation to see which events it requires)
18+
19+
For specific details on the usage of events, kindly refer to its [**API documentation**](/api/events).
20+
21+
## Enabling Events
22+
23+
Note that events are disabled by default and if you wish to enable specific events, you need to configure them in the `settings.event` object when initializing the chatbot. For example, to enable the `RcbChangePathEvent`:
24+
25+
```jsx
26+
const botSettings = {
27+
event: {
28+
rcbChangePath: true,
29+
// ... other events
30+
}
31+
};
32+
33+
<ChatBot flow={myFlow} settings={botSettings} />
34+
```
35+
36+
:::tip Tip
37+
38+
Check out the example for [**custom events**](/examples/custom_events) and experiment with the live editor!
39+
40+
:::

‎docs/concepts/hooks.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
sidebar_position: 7
3+
title: Hooks
4+
description: Understanding chatbot hooks for external component interaction.
5+
keywords: [react, chat, chatbot, chatbotify, hooks, concepts, provider]
6+
---
7+
8+
# Hooks
9+
10+
React ChatBotify provides a set of [**custom hooks**](/api/hooks) that allow your own components—those outside the main `ChatBot` component structure—to interact with and control various aspects of the chatbot. This is powerful for creating custom UI elements that can, for example, **toggle audio**, **send messages**, or **open/close the chat window**.
11+
12+
## Overview
13+
14+
Note that to use any of the custom hooks provided by React ChatBotify, your components that call these hooks **must** be descendants of the `<ChatBotProvider>` component. The `ChatBot` component itself should also be a child of this provider. We'll look at 2 scenarios below.
15+
16+
**Scenario 1:** If you have no need for custom hooks, then you **do not need** to import `ChatBotProvider` and can simply use `ChatBot`. This is likely the scenario for a vast majority of users:
17+
18+
```jsx title=MyComponent.js
19+
import ChatBot from "react-chatbotify";
20+
21+
const MyComponent = () => {
22+
return (
23+
<ChatBot/> {/* no custom hooks needed */}
24+
);
25+
};
26+
```
27+
28+
**Scenario 2:** If you require custom hooks to interact with the chatbot (e.g. toggle audio) from within your own components, you need to import `ChatBotProvider` and ensure that your components that need the hooks are nested within it:
29+
30+
```jsx title=MyComponent.js
31+
import ChatBot, { ChatBotProvider } from "react-chatbotify";
32+
33+
const MyComponent = () => {
34+
return (
35+
<>
36+
<MyNotNestedComponent> {/* unable to access custom hooks */}
37+
<ChatBotProvider>
38+
<MyNestedComponent> {/* able to access custom hooks (e.g. useAudio) */}
39+
<ChatBot/>
40+
</ChatBotProvider>
41+
</>
42+
);
43+
};
44+
```
45+
46+
```jsx title=MyNestedComponent
47+
import { useAudio } from "react-chatbotify";
48+
49+
const MyNestedComponent = () => {
50+
// can use custom hook
51+
const { toggleAudio } = useAudio();
52+
53+
return (
54+
<button onClick={toggleAudio}></button>
55+
)
56+
};
57+
58+
const MyNotNestedComponent = () => {
59+
// error, cannot use custom hook since outside of ChatBotProvider
60+
const { toggleAudio } = useAudio();
61+
62+
return (
63+
<button onClick={toggleAudio}></button>
64+
)
65+
};
66+
```
67+
68+
For specific details on the usage of hooks, kindly refer to its [**API documentation**](/api/hooks).
69+
70+
:::warning Warning
71+
It is a common mistake to import these custom hooks from a component outside of `<ChatBotProvider>`. If you're running into issues, make sure to check that your component is nested properly as a child of `<ChatBotProvider>`!
72+
:::
73+
74+
:::tip Tip
75+
An extensive example featuring how various hooks may be used can be found [**here**](/examples/custom_hooks).
76+
:::

‎docs/concepts/slots.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
sidebar_position: 8
3+
title: Slots
4+
description: Understanding how to use Slots to customize chatbot sections.
5+
keywords: [react, chat, chatbot, chatbotify, slots, concepts, customization, ui]
6+
---
7+
8+
# Slots
9+
10+
The `Slots` prop in React ChatBotify offers a powerful way to customize the visual structure of the chatbot by allowing you to replace entire major sections of its UI with your own custom React components. This provides a high degree of flexibility if you need to integrate the chatbot more deeply with your existing application's look and feel, or if you want to introduce unique functionality within these core sections.
11+
12+
## Purpose of Slots
13+
14+
Unlike the [**Styles**](/concepts/styles) prop, which allows you to change the CSS of existing components, or the [**Settings**](/concepts/settings) prop, which lets you tweak behaviors, the `Slots` prop is about replacing default chatbot UI parts with your own components. This is useful when:
15+
16+
* You need a completely different header or footer structure.
17+
* You want to embed custom interactive elements within the chatbot's main areas.
18+
* The default rendering of a section doesn't meet specific design system requirements.
19+
20+
## Type Definition
21+
22+
The `Slots` prop accepts an object where each key corresponds to a specific section of the chatbot. You provide your custom React component as the value for the key.
23+
24+
```typescript
25+
import React from "react";
26+
27+
/**
28+
* Defines the structure for custom components (e.g. header) that can be passed to the ChatBot.
29+
* Each property is optional and corresponds to a major section of the ChatBot UI.
30+
* If a component is provided, it will be rendered in place of the default component.
31+
*/
32+
export type Slots = {
33+
/** Custom component to render the header of the ChatBot. */
34+
chatBotHeader?: React.ElementType;
35+
/** Custom component to render the body/content area of the ChatBot. */
36+
chatBotBody?: React.ElementType;
37+
/** Custom component to render the input area of the ChatBot. */
38+
chatBotInput?: React.ElementType;
39+
/** Custom component to render the footer of the ChatBot. */
40+
chatBotFooter?: React.ElementType;
41+
}
42+
```
43+
44+
## Available Slots
45+
46+
You can provide custom components for the following slots:
47+
48+
* **`chatBotHeader`**: Replaces the entire header section of the chatbot. This is where the title, close button, and other header controls typically reside.
49+
* **`chatBotBody`**: Replaces the main content area where messages between the user and the bot are displayed. Use this slot with caution, as you'll be responsible for rendering the message flow if you replace it.
50+
* **`chatBotInput`**: Replaces the area where the user types their message, including the text input field and send button. Replacing this means you'll need to handle user input submission.
51+
* **`chatBotFooter`**: Replaces the footer section, which might contain branding or supplementary controls.
52+
53+
Note that for the `chatBotHeader`, the value of `settings.header.buttons` is passed in via a `buttons` prop. Similarly, for the `chatBotFooter` and `chatBotInput`, the value of `setings.footer.buttons` and `settings.chatInput.buttons` are passed in via `buttons` props respectively.
54+
55+
:::info Info
56+
57+
If a component is not provided for a slot, the chatbot will use its default component for that section.
58+
59+
:::
60+
61+
## Usage Example
62+
63+
Here's how you might replace the default header with your own custom header component:
64+
65+
```jsx title=MyChatbot.js
66+
import ChatBot from "react-chatbotify";
67+
import MyCustomHeader from "./MyCustomHeader"; // Your custom component
68+
69+
// Your chatbot flow and settings
70+
const flow = { /* ... */ };
71+
const settings = { /* ... */ };
72+
73+
const slots = {
74+
header: MyCustomHeader
75+
};
76+
77+
const MyChatbot = () => {
78+
return (
79+
<ChatBot flow={flow} settings={settings} slots={slots} />
80+
);
81+
};
82+
83+
export default MyChatbot;
84+
```
85+
86+
```jsx title=MyCustomHeader.js
87+
import React from 'react';
88+
89+
const MyCustomHeader = (props) => {
90+
91+
return (
92+
<div style={{ background: 'lightblue', padding: '10px', borderBottom: '1px solid gray' }}>
93+
<h2>My Company's Chatbot</h2>
94+
{/* Passed in by default via the chatbot */}
95+
{props.buttons}
96+
{/* You can add more custom elements here */}
97+
</div>
98+
);
99+
};
100+
101+
export default MyCustomHeader;
102+
```
103+
104+
## Considerations
105+
106+
* **Passing of Props**: React ChatBotify passes the `buttons` prop to the `chatBotHeader`, `chatBotInput` and `chatBotFooter` components. When you provide a custom component, it will also receive these props.
107+
* **Functionality Replacement**: If you replace a slot like `chatBotInput` or `chatBotBody`, you take on the responsibility of replicating the core functionality (e.g. message display, input handling, sending messages). This involves the use of [**hooks**](/concepts/hooks) and while things can get complex, you may reference the core library implementation which will be very useful.
108+
* **Styling**: Your custom components will need their own styling. They won't automatically inherit all styles from the chatbot's theme or style props in the same way default components do.
109+
110+
Using slots is a powerful feature for deep customization. Start simple, perhaps by customizing less critical sections like the `chatBotHeader` or `chatBotFooter`, before attempting to replace core functional areas like `chatBotBody` or `chatBotInput`.

0 commit comments

Comments
 (0)