Skip to content

Commit 0db5a03

Browse files
keerlukeerlu
authored
Merge pull request #5 from talkjs/docs/move-readme-to-docs-site
Update README to link to docs
2 parents 19f7223 + 8279860 commit 0db5a03

File tree

1 file changed

+81
-251
lines changed

1 file changed

+81
-251
lines changed

‎README.md

Lines changed: 81 additions & 251 deletions
Original file line numberDiff line numberDiff line change
@@ -1,286 +1,116 @@
11
# React components for TalkJS
22

3-
This library makes it easy to use the [TalkJS](https://talkjs.com) pre-built chat UIs inside a React web application.
3+
The `@talkjs/react` library makes it easy to use [TalkJS](https://talkjs.com) inside a React web application by providing React components for our pre-built chat UIs.
44

5-
`@talkjs/react` encapsulates `talkjs`, the framework-independent ("vanilla") [TalkJS JavaScript SDK](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK). It only provides React components for UI-related matters: For anything related to data manipulation, such as synchronizing user data, or creating and joining conversations, use the vanilla SDK.
5+
`@talkjs/react` encapsulates `talkjs`, the framework-independent [TalkJS JavaScript SDK](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK). For anything related to data manipulation, such as synchronizing user data, or creating and joining conversations, use the JavaScript SDK.
66

77
TypeScript bindings are included.
88

9-
If you encounter any problems with `@talkjs/react`, please open an issue. If you have a problem with TalkJS itself, or if you're not sure where the problem lies, it's better to open a chat with our support on https://talkjs.com/ (just open the chat widget). TalkJS support is staffed by engineers.
9+
If you encounter any problems with `@talkjs/react`, please open an issue. If you have a problem with TalkJS itself, or if you're not sure where the problem lies, it's better to open a [chat for support](https://talkjs.com/?chat). TalkJS support is staffed by engineers.
1010

11-
## Getting Started
11+
## Prerequisites
1212

13-
Install both `@talkjs/react` and the vanilla [TalkJS NPM package](https://www.npmjs.com/package/talkjs):
13+
- A [TalkJS account](https://talkjs.com/dashboard/login). TalkJS provides a ready-to-use chat client for your application. Your account gives you access to TalkJS's free development environment.
14+
- A [React app](https://react.dev/learn/start-a-new-react-project) that you will add TalkJS to
1415

15-
```sh
16-
npm install talkjs @talkjs/react
17-
# or
18-
yarn add talkjs @talkjs/react
19-
```
20-
21-
`@talkjs/react` is just a thin wrapper around `talkjs`. Notably, it is designed such that when you update to a new version of `talkjs` that exposes new options, methods or events, you can use these right away from the React components, without having to update `@talkjs/react` (or wait for such an update to be published)
22-
23-
## Load a UI for existing chat data
24-
25-
### 1. Create a session
26-
27-
Wrap your main app components in a session:
28-
29-
```tsx
30-
import { Session } from "@talkjs/react";
16+
## Documentation
3117

32-
//...
18+
- [Getting started guide](https://talkjs.com/docs/Getting_Started/Frameworks/React/)
19+
- [React SDK reference docs](https://talkjs.com/docs/Reference/React_SDK/Installation/)
20+
- [Team chat tutorial](https://talkjs.com/resources/how-to-use-talkjs-to-create-a-team-chat-with-channels/) and [example code](https://github.com/talkjs/talkjs-examples/tree/master/react/remote-work-demo)
3321

34-
<Session appId={/* your app ID, find it in the dashboard */} userId="pete">
35-
{/* your main app here here */}
36-
</Session>;
37-
```
38-
39-
This assumes user `pete` exists in TalkJS.
40-
41-
The session encapsulates a connection to the TalkJS realtime infrastructure, and this connection will live as long as the session component is mounted. If you want to listen for events or show desktop notifications for new messages, we recommend putting the session at the top of your component hierarchy, so it's active even when no chat UI is being shown.
42-
43-
### 2. Create a chatbox
44-
45-
Anywhere inside the children of `<Session>` you can create a `<Chatbox>`, an `<Inbox>` or a `<Popup>`:
22+
## Examples
4623

47-
```tsx
48-
import { Chatbox } from "@talkjs/react";
24+
The following examples use the [`Session`](https://talkjs.com/docs/Reference/React_SDK/Components/Session/) and [`Chatbox`](https://talkjs.com/docs/Reference/React_SDK/Components/Chatbox/) components from the React SDK to create a chatbox UI.
4925

50-
//...
26+
For both examples, you'll first need to install both `@talkjs/react` and the [`talkjs` JavaScript package](https://www.npmjs.com/package/talkjs):
5127

52-
<Chatbox
53-
conversation="welcome"
54-
style={{ width: 400, height: 600 }}
55-
className="chat-container"
56-
/>;
28+
```sh
29+
npm install talkjs @talkjs/react
30+
# or
31+
yarn add talkjs @talkjs/react
5732
```
5833

59-
This assumes conversation `welcome` exists in TalkJS, with `pete` as a participant.
60-
61-
The code above will render a `div` with the `style` and `className` passed through, and put a TalkJS Chatbox inside it. If you change the value of the `conversation` prop, the chatbox will switch to another conversation.
34+
### Add an existing user and conversation
6235

63-
## Manipulating data
36+
This example demonstrates how to create a TalkJS session with an existing user and view a chatbox UI with an existing conversation. We'll use a sample user and conversation that are already included in your [test environment](https://talkjs.com/docs/Features/Environments/).
6437

65-
If your security settings allow, TalkJS lets you create users and join conversations from the client side. This lets you synchronize user data with TalkJS in a just-in-time fashion.
38+
Add the following code to your React app. Replace the `<APP_ID>` with your test environment App ID from the **Settings** tab of the TalkJS dashboard:
6639

67-
You manipulate data exactly as you would if you directly used the [vanilla JavaScript SDK](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK).
40+
```jsx
41+
import { Session, Chatbox } from "@talkjs/react";
6842

69-
### 1. Synchronize user data
70-
71-
To create or update user data, just replace the `userId` prop by `syncUser`. This prop expects a callback that uses the vanilla TalkJS SDK to create a `Talk.User` object:
72-
73-
```tsx
74-
import { useCallback } from "react";
75-
import { Session } from "@talkjs/react";
76-
import Talk from "talkjs";
43+
function ChatComponent() {
44+
return (
45+
<Session appId="<APP_ID>" userId="sample_user_alice">
46+
<Chatbox
47+
conversationId="sample_conversation"
48+
style={{ width: "100%", height: "500px" }}
49+
></Chatbox>
50+
</Session>
51+
);
52+
}
7753

78-
//...
79-
80-
const syncUser = useCallback(
81-
() =>
82-
// regular vanilla TalkJS code here
83-
new Talk.User({
84-
id: "pete",
85-
name: "Pete",
86-
photoUrl: "https://example.com/pete.jpg",
87-
//...
88-
}),
89-
[]
90-
);
91-
92-
<Session
93-
appId={/* your app ID, find it in the dashboard */}
94-
syncUser={syncUser}
95-
>
96-
{/* your main app here here */}
97-
</Session>;
54+
export default ChatComponent;
9855
```
9956

100-
Note: you can't create `Talk.User` object before the TalkJS SDK has initialized. In vanilla JS you'd have to await `Talk.ready` promise for this, but `@talkjs/react` ensures that your `syncUser` callback is only called after TalkJS is ready.
57+
### Sync a user and conversation
10158

102-
### 2. Create and join a conversation
59+
This example demonstrates how to sync a user and conversation that you create with the JavaScript SDK.
10360

104-
Similarly, `<Chatbox>`, `<Inbox>` and `<Popup>` let you lazily create or update conversations with the `syncConversation` prop.
61+
Add the following code to your React app:
10562

106-
Just replace the `conversation` prop by a `syncConversation` callback, which will be invoked just before the chatbox is created. Then, use the provided [`session`](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Session) object to create a [`ConversationBuilder`](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/ConversationBuilder/#ConversationBuilder) using [`getOrCreateConversation`](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Session/#Session__getOrCreateConversation):
107-
108-
```tsx
63+
```jsx
10964
import { useCallback } from "react";
110-
import { Chatbox } from "@talkjs/react";
11165
import Talk from "talkjs";
112-
113-
//...
114-
115-
const syncConversation = useCallback((session: Talk.Session) => {
116-
// regular vanilla TalkJS code here
117-
const conversation = session.getOrCreateConversation("welcome");
118-
conversation.setParticipant(session.me);
119-
return conversation;
120-
}, []);
121-
122-
<Chatbox
123-
syncConversation={syncConversation}
124-
style={{ width: 400, height: 600 }}
125-
className="chat-container"
126-
/>;
127-
```
128-
129-
## Events
130-
131-
All events supported by the [TalkJS JavaScript SDK](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK) are exposed on the React components as props. For example:
132-
133-
```tsx
134-
<Session
135-
appId={/*...*/}
136-
userId={/*...*/}
137-
onMessage={message => console.log(message.body)}
138-
onUnreadsChange={unreads => console.log(unreads.length)}
139-
>
140-
```
141-
142-
All events supported by `<Session>` are listed in [the `Talk.Session` reference](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Session/#Session__methods): Any method that starts with `on` is exposed as an event prop in React.
143-
144-
Note that [`Session.unreads.onChange`](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Session/#Unreads__onChange) is exposed directly on the `<Session>` as a prop named `onUnreadsChange`.
145-
146-
Similarly, for `<Chatbox>` ([vanilla sdk](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Chatbox/#Chatbox__methods)), `<Inbox>` ([vanilla sdk](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Chatbox/#Chatbox__methods)) or `<Popup>` ([vanilla sdk](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Chatbox/#Chatbox__methods)):
147-
148-
```tsx
149-
<Chatbox
150-
conversationId={/*...*/}
151-
onSendMessage={(event) => console.log(event.message.text)}
152-
onCustomMessageAction={(event) => console.log(event.action)}
153-
onSomethingSomething={/* callback */}
154-
/>
155-
```
156-
157-
Again, any method that starts with `on` is exposed as a prop.
158-
159-
## Options
160-
161-
TalkJS supports a lot of options that let you finetune the behavior of the chat UI. Any option that can be passed to [`createChatbox`](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Session/#Session__createChatbox), [`createInbox`](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Session/#Session__createInbox) and [`createPopup`](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Session/#Session__createPopup) can be passed as a prop:
162-
163-
```tsx
164-
<Inbox
165-
// only show conversations where `custom.state != 'hidden'`
166-
feedFilter={{ custom: { state: ["!=", "hidden"] } }}
167-
showMobileBackButton={false}
168-
messageField={{ placeholder: "Write a message.." }}
169-
//...
170-
/>
171-
```
172-
173-
If any of these props change, `<Inbox>` will apply it directly through a setter such as [`setFeedFilter`](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Inbox/#Inbox__setFeedFilter). If no such setter exists, it will recreate the `Talk.Inbox`.
174-
175-
## Loading
176-
177-
TalkJS loads quickly but not always instantaneously. If you want to display something while TalkJS is loading, pass a react node to the `loadingComponent` prop:
178-
179-
```tsx
180-
<Inbox
181-
//...
182-
loadingComponent={<h1>Loading..</h1>}
183-
/>
184-
```
185-
186-
## Direct access to TalkJS internals
187-
188-
If you need to do things with your
189-
`Talk.Session`, `Talk.Chatbox`, `Talk.Inbox` or `Talk.Popup` instances that the react bindings to not let you do, you can get a direct reference to it.
190-
191-
### Using hooks
192-
193-
In any child component of `<Session>` you can call the `useSession` hook to get the `Talk.Session` object:
194-
195-
```tsx
196-
import { useSession } from "@talkjs/react";
197-
198-
function MyComponent(props) {
199-
const session = useSession(); // Talk.Session | undefined
200-
201-
useEffect(() => {
202-
if (session?.isAlive) {
203-
session.getOrCreateConversation("welcome").sendMessage("hi");
204-
}
66+
import { Session, Chatbox } from "@talkjs/react";
67+
68+
function ChatComponent() {
69+
const syncUser = useCallback(
70+
() =>
71+
new Talk.User({
72+
id: "nina",
73+
name: "Nina",
74+
email: "[email protected]",
75+
photoUrl: "https://talkjs.com/new-web/avatar-7.jpg",
76+
welcomeMessage: "Hi!",
77+
role: "default",
78+
}),
79+
[],
80+
);
81+
82+
const syncConversation = useCallback((session) => {
83+
// JavaScript SDK code here
84+
const conversation = session.getOrCreateConversation("welcome");
85+
86+
const other = new Talk.User({
87+
id: "frank",
88+
name: "Frank",
89+
email: "[email protected]",
90+
photoUrl: "https://talkjs.com/new-web/avatar-8.jpg",
91+
welcomeMessage: "Hey, how can I help?",
92+
role: "default",
93+
});
94+
conversation.setParticipant(session.me);
95+
conversation.setParticipant(other);
96+
97+
return conversation;
20598
}, []);
206-
}
207-
```
208-
209-
Note that the value may be undefined if the session has not yet loaded or has
210-
since been destroyed. See the section on liveness below.
211-
212-
### Using refs
21399

100+
return (
101+
<Session appId="<APP_ID>" syncUser={syncUser}>
102+
<Chatbox
103+
syncConversation={syncConversation}
104+
style={{ width: "100%", height: "500px" }}
105+
></Chatbox>
106+
</Session>
107+
);
108+
}
214109

215-
All `@talkjs/react` components let you assign the underlying TalkJS object to a
216-
ref:
217-
218-
```tsx
219-
const session = useRef<Talk.Session>();
220-
const chatbox = useRef<Talk.Chatbox>();
221-
222-
//...
223-
224-
onSomeEvent = useCallback(async () => {
225-
// do something with the chatbox
226-
if (chatbox.current?.isAlive) {
227-
chatbox.current.sendLocation();
228-
}
229-
// do something with the session.
230-
if (session.current?.isAlive) {
231-
const inboxes = await session.current.getInboxes();
232-
}
233-
}, []);
234-
235-
<Session /*...*/ sessionRef={session}>
236-
<Chatbox /*...*/ chatboxRef={chatbox} />
237-
</Session>;
110+
export default ChatComponent;
238111
```
239112

240-
The ref will be set once the Talk.Chatbox object has been created (resp. when the Talk.Session has initialized), and it will be set back to `undefined` once it has been destroyed.
241-
242-
### Liveness
243-
244-
Make sure you always check the `isAlive` property to ensure that the object is
245-
not destroyed because React is prone to trigger race conditions here (especially
246-
when React.StrictMode is enabled or when using a development setup with Hot
247-
Module Reloading, both of which cause a lot of destroying).
248-
249-
## Reference
250-
251-
### `<Session>`
252-
253-
Accepted props:
254-
255-
- `appId: string` - your app ID from the TalkJS dashboard
256-
- `userId: string` - required unless `syncUser` is given
257-
- `syncUser: Talk.User | () => Talk.User` - required unless `userId` is given
258-
- `sessionRef: React.MutableRefObject<Talk.Session>` - See [above](#using-refs)
259-
260-
Accepted events (props that start with "on"):
261-
262-
- all events accepted by [`Talk.Session`](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Session/#Session__methods)
263-
- `onUnreadsChange` - as in [`Unreads.onChange`](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Session/#Unreads__onChange)
264-
265-
### `<Chatbox>`, `<Inbox>` and `<Popup>`
266-
267-
Accepted props:
268-
269-
- `conversationId: string` - Selects this conversation. If the conversation does not exist, the "Not found" screen is shown.
270-
- `syncConversation: Talk.ConversationBuilder | () => Talk.ConversationBuilder` - Creates or updates the given conversation using the supplied ConversationBuilder, then selects it.
271-
- `style: CSSProperties` - Optional. Passed through to the `div` that will contain the chatbox
272-
- `className: string` - Optional. Passed through to the `div` that will contain the chatbox
273-
- `loadingComponent: ReactNode` - Optional. A react node which will be shown while the chatbox is
274-
loading
275-
- `chatboxRef` (resp. `inboxRef`, `popupRef`) - Pass a ref (created with `useRef`) and it'll be set to the vanilla JS [Chatbox](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Chatbox/) (resp. [Inbox](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Inbox/), [Popup](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Popup/)) instance. See [above](#using-refs) for an example.
276-
- All [Talk.ChatboxOptions](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Session/#ChatboxOptions)
277-
278-
Accepted events (props that start with "on"):
279-
280-
- All events accepted by [`Talk.Chatbox`](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Chatbox/#Chatbox__methods) (resp. [Inbox](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Inbox/#Inbox__methods), [Popup](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Popup/#Popup__methods))
281-
282-
Note: For `<Chatbox>` and `<Popup>`, you must provide exactly one of `conversationId` and `syncConversation`. For `<Inbox>`, leaving both unset selects the latest conversation this user participates in (if any). See [Inbox.select](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Inbox/#Inbox__select) for more information.
283-
113+
For more details and explanation, see our [getting started guide](/Getting_Started/Frameworks/React/).
284114

285115
## Contributing
286116

@@ -292,7 +122,7 @@ Should you want to contribute, please take note of the design notes below.
292122

293123
## Design notes
294124

295-
This library has been designed to be maximally forward-compatible with future TalkJS features. The `talkjs` package is a peer dependency, not a direct dependency, which means you can control which TalkJS version you want to be on. It also means you won't need to wait for a new version of `@talkjs/react` to be published before you can get access to new TalkJS features.
125+
This library has been designed to be maximally forward-compatible with future TalkJS features. The `talkjs` package is a peer dependency, not a direct dependency, which means you can control which TalkJS version you want to be on. It also means you won't need to wait for a new version of `@talkjs/react` to be published before you can get access to new TalkJS features.
296126

297127
From our (TalkJS) perspective, it means we have a lower maintenance burden: we can ship new JS features without having to update (and test and verify) `@talkjs/react`.
298128

0 commit comments

Comments
 (0)